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PREFACE 


Intercomm is a state-of-the-art teleprocessing monitor system 
executing on the IBM System/370 family of computers and operating under 
the control of IBM Operating Systems (MVS/370, XA and ESA). Intercomm 
monitors the transmission of messages to and from terminals, ¢oncurrent 
message processing, centralized access to I/0. “files, and“ the routine 
utility operations of editing input messages and formatting output 
messages, as required. , 


: *The PL/1 Programmers Guide explains the organization of Intercomm 
ron the application programmer's point of view and’ illustrates the 
procedures for creating PL/1. application programs and integrating them 
into the Intercomm environment. 


Syntax used in describing the coding of JCL or application 
program statements is: nr 
e { } A pair of braces indicates the, presence of a choice: 

code elements contained within the braces represent 
alternatives, one, of which must be chosen. The braces 
are not to be coded. ‘ 


e [ ] A pair of brackets indicates an optional parameter which 
may be omitted depending on access requirements as 
described in the accompanying text. The brackets are not 
to be coded. : 


e A parameter consisting partially or solely of lower case 
letters represents the generic (Intercomm) name of the value. 
The programmer must substitute the actual name used for 
defining the data area within the specific program., 


= i Bean AY a . 
As a prerequisite to this manual, it if assumed that the user is 
familiar with the Intercomm Concepts and Facilities Manual. The 


following manuals describe in further detail facilities referenced in 
this manual: 


e Message Mapping Utilities 

e Utilities Users Guide 

e Store/Fetch Facility Users Guide 

e Dynamic Data Queuing Facility ~ ~ 
e Page Facility aaa Se — 
e Operating Reference Manual:,. “iessage’ Management" 


‘erie Management" 
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Chapter 1 


INTRODUCTORY CONCEPTS OF ON-LINE SYSTEMS 


1.1 INTRODUCTION 


The objective of most on-line systems is to reduce the time 
factor from source of input data to the results of data processing. 
Typical on-line systems applications in the business environment are: 


e Data Collection 


Transactions may be edited partially on receipt, batch totals 
may be transmitted and verified, but the bulk of processing 
of the collected data takes place in the batch mode off-line. 


e Inquiry/Update Systems 


Transactions are processed immediately to retrieve and/or 
update information in an on-line data base. 


e Message Switching 


Transactions consist of administrative data to be rerouted to 
other terminals in the system. 


On-line systems are characterized by a mode of operation which is 
nonscheduled and transaction-oriented. An operator at a terminal 
remote from the data processing center enters a transaction (unit of 
work) by transmitting a message over communication facilities. Each 
individual transaction is processed immediately, as opposed to batch 
systems, where transactions are accumulated for processing on a 
periodic basis (monthly, daily, etc.). 


Online systems are designed to satisfy a response time 
requirement which is the elapsed time between a request for processing 
of an input message from a terminal to receipt of an acknowledgement, 
or response to that input message (completion of a transaction). 


1.2 THE ON-LINE SYSTEM ENVIRONMENT 


Typical on-line message processing application programs operate 
on one transaction at a time as they come in from terminals. 
Application programs are usually designed to process only one type of 
transaction, and the whole environment can be said to be transaction 


oriented. Input messages can be processed as received, in any order, 
and the files to be referenced should not be read from beginning to end 
for each transaction. Instead, the records in files are accessed 


directly, either through a specific key or some form of cross-reference 
look-up. 
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A few applications might require some sequential or list 
processing of a file, and while this is possible, message processing 
times for such applications would tend to be high. 


Figure 1 shows a computer system schematic depicting a memory 
layout with an on-line system such as Intercomm, operating in a region 
or address space as a job under an operating system such as IBM's MVS. 
The on-line system has its own Transaction Monitor which schedules the 


activation of transaction processing according to the varying demands 
in message traffic. 
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TRANSACTION ) FILE 
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Figure 1. On-line Transaction Processing in a 
Multiprogramming Environment 
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The transaction processing programs do not conduct input or 
output operations with the terminals. This function is provided by the 
on-line system, which reads input messages from terminals and saves 
them (queues them) until the appropriate processing program can be 
activated (scheduled). The message is then retrieved from the queue 
and passed directly to the processing program by the Monitor. The 
processing program then requests the Monitor to queue its output 
response message, and the Monitor handles the terminal output function. 


1.3 BATCH ENVIRONMENT VS. ON-LINE ENVIRONMENT 


The classical batch processing system flow of 
input/process/output can be expanded to include message queuing and 


retrieving in the on-line environment. However, the typical on-line 
application program need only be concerned with actual transaction 
processing, because the on-line system does the rest. Figure 2 


summarizes some of the differences between batch and on-line 
environments. 


Online 


Scheduled input Unscheduled input 


Single-application job Multiple-application job 


Delayed processing of transactions | Immediate processing of individual 
in batches by type transactions by type 


Transaction input, processing, and | Terminal input/output events are 
output controlled by processing asynchronous to the processing 
program logic program 


Figure 2. Differences Between Batch and On-line Environments 
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1.4 SINGLE-THREAD VS, MULTITHREAD PROCESSING 


In the on-line environment, the logical path of a program in 
execution is called a thread. A single-thread system processes one 
message at a time. However, in a multiple application environment, 
message volume is such that all message traffic could not be adequately 
serviced in a single-thread mode, Large queues (waiting lines) tend to 
develop because messages arrive faster than they can be processed. To 
alleviate this problem and improve system throughput, the delay time in 
the processing of one message waiting for an I/O operation may be used 
for simultaneously processing another message. In this way, several 
message processing logic paths, or threads, may be active at once. 
This is referred to as multithreading. 


Multithreading is coordinated by the Transaction Monitor, and, 
depending on message traffic, can occur between two or more programs or 
within a single program. 


To illustrate this, let us assume that we have two transaction 
processing programs, A and B, and that three messages have arrived for 
processing; two A-type transactions and one B-type transaction. 
Programs A and B both require access to records in a file, affording an 
opportunity for some processing overlap or multithreading. 
Multithreading would occur between programs A and B if while program A 
is waiting for file retrieval, program B is activated by the Monitor to 
carry out its message processing. However, if program A were 
reentrant, that is, written in such a way that it could handle more 
than one thread at a time, then multithreading could also occur within 
program A. This means that while reentrant program A is waiting for a 
file retrieval for the processing of one message, it may be activated 
again to carry out the parallel processing of a second, or nth, 
message. Figure 3 illustrates these concepts. 
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Figure 3. Multithreading in an On-line Environment 
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1.5 ° PROGRAM FUNCTIONS IN THE ON-LINE ENVIRONMENT 


An on-line system consists of programs to serve four different 


functions: 


e Line Control and Terminal Control 


Servicing input requests from the various terminal types 
including transmission error recovery 


Directing output to the various terminal types including 
transmission error recovery 


Intercepting and storing messages to non-operational 
devices, and retrieval of messages when devices become 
operational 


Translation of messages to and from terminal transmission 
code and EBCDIC code for processing 


e Message Processing Control 


Queuing new input messages until the associated message 
processing program is scheduled for execution 


Scheduling message processing programs to obtain best 
system throughput for message traffic 


Controlling multithread operation for concurrent 
processing of several messages 


Centralizing data file accesses to eliminate redundant 
operations and provide exclusive control over records 
during file updates 


e Systems Operation Control 


Security checking functions to restrict certain 
transactions to specific operators and/or terminals, and 
to prevent access to unauthorized functions/files. 


Logging (journaling) of all message traffic 


Checkpointing, Message Restart, File Recovery and 
Backout-On-The-Fly (dynamic file backout) facilities 


Cancellation of message processing programs when a - 


program check or program loop occurs 
Collect and display system statistics 


Display and modify system status 
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e Message (Transaction) Processing 


-- Editing text data from terminal input, including format 
conversion and content editing of individual fields 


-- Retrieval and updating of data from on-line files or data 
bases 


-- Preparation of response (output) messages to terminals 


-- Queuing of response messages for output to terminals 


1.5.1 Monitor Control Functions 
The Intercomm System provides complete facilities for: 
e Line control and terminal control 
e Message processing control 


e Systems operation control 


1.5.2 Application Processing Functions 


Transaction processing logic lies within the coding domain of the 
application programmer. Intercomm provides the following message and 
file handling support: 

e Format conversion and editing of input fields 


e Centralized control of data files 


e Format conversion and placement of constant and variable 
information in response messages and terminal displays 


© Queuing. of messages (for the same or another terminal, or 
another application) 


The installation-dependent application logic functions then need 
include only the following: 


e Content editing of individual input message fields 
e Retrieval and updating of data from on-line files 


e Selection of individual fields for the output message(s) 
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MESSAGE PROCESSING AND CONTROL UNDER INTERCOMM 


2.1 THE INTERCOMM ENVIRONMENT 


Intercomm operates under MVS as a job in a region or address 
space. The job is loaded at the beginning of on-line operations and 
continues to operate until the terminal network is closed down. 
Intercomm contains many system programs and application subsystems. - 
Intercomm system programs include the Monitor and other subprograms to 
handle such things as terminal and peripheral 1/0 operations. 
Subsystems are message processing application programs activated by the 
monitor. The term "subsystem" includes both application-oriented 
message processing programs written by users and Intercomm system 
command processing and utility programs. The Intercomm region contains 
the execution module itself plus dynamically allocated storage or work 
space, as illustrated in Figure 4. 


TO PERIPHERAL 
ON-LINE DEVICES 
TERMINALS COMPUTER 


OPERATING SYSTEM 
REGIONS 
SYSTEM 
PROGRAMS 


MESSAGE 
PROCESSING 
SUBSYSTEMS 


Figure 4. The Intercomm Environment 
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The system programs are time- or event-driven; the subsystems are 
message-driven. The Intercomm Monitor calls system programs to handle 
events and exceptional conditions as they occur, for example, terminal 
and peripheral I/O interrupts, time-dependent processing, excessive 
message traffic, and system operator commands. 


A subsystem, on the other hand, is called by the system monitor 
when there are messages queued for it, and it has been scheduled for 
execution. Subsystems, while executing, can call user subroutines or 
call system programs to perform services, such as accessing data files 
and queuing messages for output or additional processing by other 
subsystems. Figure 5 shows that called system programs and user 
subroutines will always return to the calling subsystem (or 
subroutine), just as the subsystem itself, executing as a subroutine of 
Intercomm, must always return to the system monitor that originally 
activated it. 


SYSTEM PROGRAMS TRANSACTION SUBSYSTEMS 


MONITOR PROGRAM AA SYBSYSTEM 
CALL SUBAA ENTRY AA 


CALL SYSX 


CALL AB 


PROGRAM AC 


SUBSYSTEM 
nn 


Figure 5. Intercomm Control Sequence 
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2.2 SYSTEM COMPONENTS 
On-line system component programs are often categorized as 
resident or nonresident, system or user, but typical on-line 


terminology also distinguishes between Front End and Back End system 
components. 


2.2.1 Front End 


The Front End communicates with and monitors all terminals in the 


network. It receives and sends messages, checks validity, performs 
security checking if specified, and accomplishes appropriate code 
translation. The Front End communicates with the Intercomm message 


processing Back End via input message queuing and output message 
dequeuing routines. Although Intercomm has its own VTAM Front End, it 
can also interface with other software Front Ends such as TCAM and 
BTAM. 


2.2.2 Back End 


The Back End accomplishes all message processing control, system 
operation control, and processing of individual messages. It is, 
essentially, the "director" of the entire on-line system operation. 


The Front End and the Monitor portion of the Back End are always 
resident, whereas message processing subsystems can be any combination 
of resident and loadable. (See Figure 6.) The decision to make a 
message processing subsystem permanently resident, or loadable, is 
based upon the trade-offs between response time, frequency of use, and 
total system core storage requirements. 
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2.3 SYSTEM PROGRAMS 


Intercomm system programs are written in Assembler language and 
include the Monitor, File Handler, high-level language interface 
routines to maintain reentrancy, and message processing service 
routines. 


The Monitor interfaces with the Front End via message queues and 
controls the processing of messages by subsystems. It is essentially a 
traffic director, analyzing message traffic and scheduling subsystems 
based upon traffic volume and priority criteria. The Monitor has four 
key components: 


@ The TP queuing interface, which communicates with the Front 
End to dequeue input messages or to queue output messages 
created by subsystems. 


© The Subsystem Controller, which schedules, loads and 
activates the application subsystems, and performs clean up 
processing when the subsystem returns. 


e The Dispatcher, which controls the execution of all events in 
the system to accomplish multithreading. 


e The Resource Manager, which allocates/deallocates and 
controls dynamic resources (such as core storage) used by 
system and application programs. 


The File Handler is the central Intercomm routine where all 
peripheral I/O service for data files is controlled. The File Handler 
issues OPENs, CLOSEs, GETs, PUTs, READs, and WRITEs via the operating 
system data management facility. Subsystems merely call an appropriate 
File Handler routine. Therefore, all access methods supported by 
Intercomm are available to any subsystem program, regardless of the 
programming language used. The File Handler maintains a single set of 
control blocks for each file defined to it via standard Job Control 
Language Data Definition statements, and all programs share this one 
set of control blocks. Intercomm can control overlapping of peripheral 
I/O processing, as well as provide standardized error analysis. A file 


is usually opened only once during an on-line session: at system 
startup (optional), or if not, then at the time the first I/O is 
requested. Since files can be accessed concurrently by different 


subsystems, an exclusive control feature is provided to eliminate 
difficulties arising when two or more subsystems (or subsystem threads) 
attempt to update the same record at the same time. 


Language interface routines are described in Chapter 3. : 
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Figure 6. Intercomm System Components 
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The basic message processing service routines are: 


e  FESEND--which passes an output message to the Front End for 
transmission to a terminal. 


e LOGPUT--which copies a message onto the system log whenever 
called by a system program or user subsystem. 


@ MESSAGE COLLECTION--which handles the queuing and dequeuing 
of all messages destined for subsystems. 


Intercomm provides service routines to convert terminal-dependent 
input messages to a terminal-independent form for application 
processing. This transformation includes removal of terminal-dependent 
control characters and conversion of numeric data fields to fixed 
decimal or binary form, if required. Similarly, for output messages, 
service routines provide transformation from terminal-independent 
results of application subsystem processing to terminal-dependent 
messages for transmission. This includes insertion of terminal- 
dependent control characters, conversion of numeric fields to character 
format, if required, and inclusion of title information, if specified. 
Each of these routines function via user-specified descriptions 
(tables) of input and output message formats. These service routines 
are: 


e Message Mapping Utilities 


This is a set of service routines called by an application 
program to perform the device-dependent transformations 
specified by the user for both input and output messages. 
Validity checking, conversion, justification and 
padding/truncation of data fields is also performed. This 
utility also executes output message disposition 
(queuing/spooling), if requested. 


@ Edit Utility 


This is a service routine called by the Monitor to process 
input messages, performing device-dependent transformations, 
and field validity checking, conversion and padding according 
to user-specified editing characteristics. 


e Output Utility 
This is a service routine executing as a subsystem to process 
output messages by performing device-dependent 


transformations, and then pass the messages to the Front End. 


For detailed documentation of these facilities, see Message 
Mapping Utilities and the Utilities Users Guide. . 
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( Other service routines of the Intercomm system for processing 
requests associated with special subsystem design requirements are: 


e Store/Fetch 


This facility allows a subsystem to save and retrieve a 
temporary or permanent data string identified by a 
user-defined key. One or more subsystems can access each 


stored data string. (See Store/Fetch Facility.) 


e Dynamic Data Queuin DD 


This facility allows a subsystem to save and retrieve a set 
of related data strings (a data queue) identified by a 
user-defined name. One or more subsystems can access each 
DDQ which may be transient or permanent. A DDQ may also be 
used for collecting messages destined for another subsystem, 


a printer, or even a batch program. (See Dynamic Data 
Queuing. ) 


e CRT Page Facility 


This facility allows a subsystem to write a set of output 
messages to a CRT terminal-oriented Page Data Set. The first 
message of a set is also sent to the Front End 
automatically. The terminal operator may then enter commands 
processed by the Page subsystem to retrieve and browse 


z through the pages of a set of output messages. (See Page 
Facility.) 


e Data Base Management System Support (DBMS 


This facility consists of separate service routines for each 
supported DBMS (IDMS, System 2000, Model 204, ADABAS, TOTAL, 
DL/I, or a user DBMS), which allows access to the DBMS from 


Intercomm. (See the Data Base Management System Users 
Guide. ) 


e Dynamic File Allocation (DFA) 


This facility allows a subsystem to create (allocate) and/or 
access a sequential data set, or to access a VSAM data set, 
specifying its DSNAME as part of subsystem logic, rather than 
with execution JCL. (See Dynamic File Allocation. ) 


© Signed-on Operator-Id Checking 


When executing under the security control of the Intercomm 
Extended Security System, a subsystem may call a _ service 
routine (SECUSER) to determine the user-ID of the operator at 
the terminal from which the transaction to be processed was 


entered. (See Extended Security System.) 
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2.4 SUBSYSTEMS 


Intercomm-supplied subsystems are written in reentrant Assembler 
Language, and include the Output Utility, the Change/Display Utility, 
the Page Browsing Subsystem and many command processing subsystems. 


The Output Utility allows a programmer to specify predefined 
report and display formats so that simply constructed output messages 
from a subsystem can be expanded, columnized, headed and subheaded, and 
displayed upon different types of devices without concern to the 
subsystem creating the message. Output Utility display formats can be 
changed without program modifications. 


The Change/Display Utility allows simple inquiry and file 
maintenance via predefined keyword input messages from terminals 
causing access to data files defined by tables. The Display Utility is 
used in conjunction with the Output Utility to produce varied report or 
display formats. 


The Page Facility processes commands from CRT-type terminals to 
browse through a file of output display screens created by the PAGE 
system program. Subsystems make use of this feature by calling the 
page storage program during message processing. The terminal operator 
interacts with the Page Facility directly. 


Command processing subsystems process Intercomm standard messages 
to accomplish the start/stop of system functions, message switching 
between terminals, displaying and changing the status of system control 
parameters, display of statistics, etc. The commands and text syntax 


are described in System Control Commands. 


User-supplied subsystems accomplish application-dependent message 
processing. Each may call any Intercomm service routine or 
user-supplied subroutine, and may be written in COBOL, Assembler or 
PL/1. 


2.4.1 Reentrant vs Nonreentrant Subsystems 


In an interactive on-line environment, the probability is very 
high for more than one terminal operator to enter concurrent requests 
to be processed by the same subsystem. To accomplish the 
multithreading of concurrent requests, application subsystems should be 
coded as reentrant, that is, variable data is defined as AUTOMATIC and 
processed in a dynamic storage area (DSA) obtained for the exclusive 
use of one processing thread. Since PL/l1 manages its own storage 
depending upon variable characteristics and attributes, an interface is 
provided which obtains a unique area of storage (from Intercomm 


administered core pools) for each iteration (thread) of each PL/1 


subsystem. The storage area is passed to the PL/l program for use as 
an ISA (Initial Storage Area). Further details of this interface, and 
program coding requirements are described in Chapter 3. 
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2.5  INTERCOMM TABLES 


Intercomm is a generalized on-line system monitor, requiring 
information about specific operating characteristics of a particular 


installation. This information is supplied in the form of tables 
generated with Intercomm macro instructions. Application programmers 
are usually not involved in defining the Intercomm tables, except for 
table specifications which pertain to their own applications. The 


basic tables controlling message processing are as follows: 
e Front End Verb Table (BITVRBTB 


A table listing all valid transaction identifiers (verbs), 
and relating them to the subsystem required for message 
processing. There is one entry per verb, defined via a 
BIVERB macro. 


e Front End Network Table 


Tables describing the terminal network (relating individual 
devices to five-character station identifications), device 
hardware and operating characteristics, and output message 
queuing specifications. 


e Back End Station Table (PMISTATB) and Device Table (PMIDEVTB 


Tables describing terminal identifications and 
device-dependent characteristics to the Message Mapping 
Utilities and/or the Edit and Output Utilities. 


e System Parameter List (SPA 


A table describing system-wide operating characteristics. 
This table may be extended to include installation-defined 
table entries, accessible to all user subsystems and 
subroutines (see Chapter 8). This table is generated via the 
SPALIST macro. 


e Data Set Control Table (DSCT) 


A table generated by the File Handler describing on-line data 
sets. Information in this table is derived from JCL and file 
control (FAR) parameters at execution startup time. 


e Subsystem Control Table (SCT) 


A table listing the program properties (reentrancy, language, 
entry point, etc.), message queue specifications (core and/or 
disk queues), and scheduling (resident or loadable, 
concurrent message processing limits, priority, etc.) for 
each subsystem. There is one entry per subsystem, defined 
via a SYCTTBL macro. 


The above listed tables are described in detail in the Operating 
Reference Manual. Additional tables describe detailed functions for 
the system programs, service routines and utilities. 
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2.6 INTERFACING WITH THE INTERCOMM MONITOR 


Each message processed by Intercomm consists of a 42-byte header 
prefix, plus application-oriented message text. The message header is 
prefixed to each input message by the Front End and is analyzed by the 
System Monitor for all message processing control. The particular 
fields of the header which control message routing are Receiving 
Subsystem Code (MSGHRSC) and Receiving Subsystem Code High-Order 
(MSGHRSCH) . This two-byte code is initialized by the teleprocessing 
interface when it constructs the header from the verb supplied at the 
beginning of the message text. The Front End Verb Table relates user 
verbs to their corresponding subsystem codes via coding of BTVERB 
macros (see Basic System Macros) in a user member USRBTVRB copied into 
the system BTVRBTB which contains the Intercomm system verbs. 


All subsystems are defined to Intercomm by an entry in the 


Subsystem Control Table (SCT). There is one entry for each subsystem 
which defines the program's general characteristics, scheduling 
requirements and message queuing specifications. Each subsystem must 


be assigned a unique two-character subsystem code for message routing. 
Definition of Intercomm system subsystems for utility and command 
processing is provided in the released member INTSCT. 


The Subsystem Control Table entry for each user subsystem is 
defined using the SYCTTBL macro which is coded in a user member USRSCTS 
copied into the system INTSCT at assembly time. A full description of 
the macro may be found in the Intercomm Basic System Macros manual. 


Many installations assign the responsibility of coding the 
Subsystem Control Table entries for individual user subsystems to the 
application programmer. At other installations, the Intercomm System 
Support Manager performs this task. In either case, the SYCTTBL macros 
must be coded with care, as there is one table controlling all user and 
system subsystems in operation when Intercomm is executing. 


The most significant SYCTTBL macro parameters for PL/1 subsystems 
are: 


e LANG=RPLI1 


For reentrant PL/1 subsystems (REENTRANT coded for OPTIONS on 
mainline PROC statement); LANG=PL1 if nonreentrant. 


e SBSP=xxxxxxxx or LOADNAM=xxxxxxxx (for dynamic load) 


Specifies the subsystem entry, that is, the main PROC name of 
the PL/1 subsystem (SBSP), or the load module name (LOADNAM) . 


e SPAC=nnnnnn 


Specifies for PL/1 subsystems, the amount of ISA the 


interface routine PREPLI should acquire, clear to binary 
zeros, and pass to the PL/1 initialization routine (PLICALLB) 
for each message being passed to this subsystem (program DSA 
size, plus DSA sizes of called user PL/1 subroutines, plus 
2000 bytes). Use PL/1 compiler STORAGE option to determine 
DSA sizes. 
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PLILNK=( BASED } 
{ NONBASED } 


Indicates whether the parameters passed by Intercomm to the 
PL/1 subsystem are to be in the non-standard ‘BASED’ forn, 
whereby the program expects to receive them in the form of 
dummy arithmetic scalars, or whether the program expects the 
parameters in the form of Locator/Descriptors for standard 
character strings (default). Further details of program 
linkage techniques are described in Chapter 3. 


TCTV=nnn 


Expected maximum processing time (in seconds) in a 
high-volume environment before the subsystem is assumed to be 
looping, or in an extended wait for file or data base access, 
and should be timed out. Considerations for this value 
depend on subsystem processing such as data base access, file 
updates, number and type of file accesses, exclusive control 
for file updates, number of output messages created, enqueue 
lock-out possibilities, etc. 


MNCL=nn 


Specifies the maximum number of concurrent threads that can 
be executed through this specific subsystem during a high 
activity period (when more than one operator enters 
transactions routed to this subsystem). 


RESOURC=name 


This parameter is used to control concurrent access to a 
resource (file, table, data base, etc.) across several 
subsystems in one Intercomm region. The name is also coded 
for the ID parameter of a RESOURCE macro (coded before all 
SYCTTBLs in the SCT) which identifies the shared resource and 
the maximum concurrent subsystem threads that may be 
activated for that resource. Note that the maximum share 
count coded on the RESOURCE macro overrides the combined MNCL 
value for all the subsystems "naming" that resource. An 
internal enqueue is issued (no time-out). While using this 
feature will affect response time during peak activity, it 
does not affect the TCTV for a subsystem, which goes into 
effect after shared control of the resource is granted. 


2.7 INTERCOMM MESSAGE HEADER 


The 


Intercomm message header is constructed by the Front End for 


each message when it arrives from a terminal. New messages created 
within the subsystem must be prefixed with the standard forty-two-byte 
header format, which is constructed by copying the input message header 
to an output message area and then altering appropriate fields. Figure 
7 lists the names and formats of all the fields in the message header, 
and describes their contents and changeability. 
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Description 


Length of message including 
header (binary number) 


Teleprocessing segment I/0 code: 
02/F2=full message; 

00/FO=header segment; 
01/Fl=intermediate segment 
03/F3=-final (trailer) segment 


Monitor message number assigned by 
Message Collection (binary) 


Terminal identification (originating 
terminal on input messages, 
destination terminal on output) 

or Broadcast Group name 


MSGHCON+1 Subsystem return code (for log code 
(MSGHRETN) X'FA’ entries only) 


Front End message number-Rel 10 
(binary) 


Used for special processing 
by the Front End (MSGHBMN - Rel 9) 


MSGHLOG 
MSGHBLK 


Verb or message identifier 
interpreted by receiving subsystem 
d FESE 


Figure 7. Intercomm Message Header Fields (Page 1 of 2) 
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Must be filled in for intersubsystem message switching and 
output messages passed to FESEND (MSGHVMI should be set to 
X'57' or X‘'67', as appropriate, for output messages passed 
directly to FESEND) 


Should be filled in for user's own information (required by 
Intercomm for message restart/file recovery and Log Analysis) 


Do Not Touch (must be copied from input to output message 
header area) 


May be modified for user codes based on subsystem logic 


* The period represents a one-byte message thread number (for resource 
Management and/or message restart purposes). 


**MSGHUSR is used by Intercomm modules as follows: 


Ls, 


If the BTVERB macro for the input verb has HPRTY=YES coded; 
contains a C'P’' to request priority queuing for the 
subsystem. The user may move a C’P' to this field to request 
priority queuing for output messages to a terminal (via 
FESEND) or to another subsystem (via Message Collection). 


For messages to be processed by the Edit Utility, contains a 
C'F’' to indicate that the input message was from a 3270 CRT 
and contains SBA sequences. 


For output messages to a switched async device (Teletype, 
Dataspeed 40, and 2740); a C’'B’ requests disconnect after 
transmitting the output message. 


For output messages to a switched Teletype or Dataspeed 40 
device; a C’X’ requests using the alternate call-list for the 
next input message (as described in the BTAM Terminal Support 
Guide). 


For output messages discarded by the Front End, a C’'F’ 
indicates the message was flushed by command, a C'Z' that it 
was discarded by the VTAM OTQUEUE user exit (Rel 10 only). 


If none of the above considerations are applicable, the subsystem 
may use this field for messages queued to other user subsystems, 
or for special logging information. The LOGPRINT utility always 
prints the value coded in this field (in hexadecimal). 


Figure 7. Intercomm Message Header Fields (Page 2 of 2) 
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2.7.1 MSGHQPR and MSGHVMI Fields 


In general, a PL/1 application subsystem does not need to be 
concerned with the MSGHQPR field, unless processing long input from a 
Teletype or similar device where message input may be segmented. In 
this case, the DDQ Facility must be used to store and forward the input 
Message segments. Otherwise, input messages from the Front End always 
contain a QPR of C’2'. Both MMU and the Output Utility set the QPR to 
X'02’' for output messages unless the Output Utility finds it necessary 
to segment an output message, in which case a segment code is used. 
The various uses of the MSGHVMI field for input and output message 
processing may be determined from the index references to this field at 
the end of this manual. 


2.8 INTERCOMM MESSAGE FLOW USING MESSAGE MAPPING 


The interaction of Intercomm system components, tables and 
subsystems with the Message Mapping Utilities (MMU) is summarized in 
Figure 8; the path of one input message and its corresponding output 
message is traced, and the numbered arrows in the diagram correspond to 
the numbered paragraphs below. 


1 The Front End reads an input message and prefixes a 42-byte 
control header containing routing information, time, date, 
originating terminal and message length. The message is then 
queued for subsystem processing by Message Collection. 


2 The System Monitor schedules the subsystem and retrieves the 
message based upon the Subsystem Control Table (SCT) 
scheduling criteria. 


3 The message is passed to the subsysten. 


4 Input in terminal-dependent format is transformed to a 
terminal independent form by a call to a Message Mapping 
Utility (MMU). 


5 The subsystem performs message processing logic, requesting 
I/O service functions from the File Handler or Data Base 
Manager interface. 


6 The subsystem creates one or more terminal-dependent output 
messages by calling MMU. 


7 The subsystem passes the message formatted by MMU to the 
Front End by a call to FESEND (unless MMU is asked to perform 
this function). 


8 The subsystem returns control to the System Monitor, passing 


a return code indicating normal completion or an error 
condition. 
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In the Intercomm multithread environment, this same sequence of 
events is carried out concurrently for many messages. 


TABLE 


(1) MESSAGE 
FRONT END COLLECTION 


MESSAGE 
MAPPING 
UTILITIES 


SYSTEM APPLICATION 
MONITOR SUBSYSTEM 


FESEND 


ACCESS FILE HANDLER 
METHOD OR OR DATA BASE 
DATA BASE MANAGER 

MANAGER INTERFACE 


Figure 8. Intercomm Message Flow Using Message Mapping 
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2.9 INTERCOMM MESSAGE FLOW USING EDIT AND OUTPUT 


The path of one input message and its corresponding output 
message is traced in Figure 9; the numbered arrows in the diagram 
correspond to the numbered paragraphs below. 


1 The Front End reads an input message and prefixes a 42-byte 
control header containing routing information, time, date, 
originating terminal, and message length. The message is 
then queued for subsystem processing by Message Collection. 


2 The System Monitor schedules the subsystem and retrieves the 
message based upon the Subsystem Control Table (SCT) 
scheduling criteria. 


3 The Edit Utility is called (if required) and the input 
message is edited according to the Edit Control Table (ECT). 


4 If Editing is not successful due to invalid input data, the 
Edit Utility optionally creates an error message for the 
originating terminal and queues it for the Output Utility by 
calling Message Collection. The subsystem is not activated. 


5 If Editing is successful, the edited message is passed to the 
subsystem. If editing is not required, the unedited message 
is passed directly to the subsystem. 


6 The subsystem performs message processing logic, requesting 
I/O service functions from the File Handler or Data Base 
Manager interface. 


7 The subsystem creates one or more output messages and queues 
them for the Output Utility by calling Message Collection 
(COBPUT) . 


8 The subsystem returns control to the System Monitor, passing 
a return code indicating normal completion or an error 
condition. 


9 The System Monitor schedules the Output Utility and passes 
the output message(s) to it for processing. 


10 The Output Utility performs formatting, if specified in the 
Message header, according to entries in the Output Format 
Table (OFT), finally passing the message to the Front End via 
a call to FESEND. 


11 The Output Utility returns to the System Monitor. E 


24 


9 


Chapter 2 Message Processing and 
Control Under Intercomm 


MESSAGE 
COLLECTION 


1 © © 
UTILITY 


OUTPUT SYSTEM APPLICATION 
UTILITY MONITOR SUBSYSTEM 


ACCESS FILE HANDLER 
METHOD OR OR DATA BASE 
DATABASE MANAGER 

MANAGER INTERFACE 


Figure 9. Intercomm Message Flow Using Edit and Output 
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2.10 THE INTERCOMM SYSTEM LOG 


The Intercomm system log (INTERLOG) provides system journaling 
and maintains a historical record of all traffic within the system. 
Complete documentation of performance during on-line processing is 
thus provided, along with system control for restart/recovery. 


Message traffic is recorded at the time of entry on a subsystem 
queue, and at the time message processing begins and ends within each 
subsystem. Subsystems may make user entries on the system log by 
calling an Intercomm system program (LOGPUT). 


An installation may suppress some or all log entries, depending 


on its own requirements. The system log is optionally used at 
Intercomm system restart time to restore message traffic within the 
system at the time of failure. The logging entries are blocked and 


written to a variable-length sequential data set which may reside on 
disk or tape. 


Log entries are in one of two formats: HT--42-byte message 
header and full text, as the message arrives from a terminal and is 
queued for a subsystem, or queued for a terminal; or HO--header-only 
entries, to mark progress through the system or error conditions. 


Log entries are identified by a code in the MSGHLOG field of the 
message header. The time and date stamps (MSGHTIM and MSGHDAT) in the 
message header are updated for each log entry. 


Progress of a message through a specific subsystem, or through 
the Front End, is indicated by the same Monitor Message Number 
(MSGHMMN) in each log record (01-30-FA or F2-F3). Complete progress 
of a message, from the first processing subsystem to final 
transmission, is indicated by the same Front End Message Number 
(MSGHBMN). The log may be printed completely or selectively via the 
Intercomm off-line utility LOGPRINT, described in the Operating 
Reference Manual. 


A timing analysis utility (Log Analysis), which is supplied with 
Intercomm, may be used off-line to produce a report of message queuing 


and processing time. Statistics for messages by terminal, verb, 
subsystem, and/or system totals are provided. See the Operating 


Reference Manual. 


The logging entries may be input to user-written batch programs 
to provide performance analysis in detail, such as traffic vs. network 
configurations, accounting routines, etc. 


Figure 10 illustrates the log entries for one input message and a 
corresponding output message generated via the Output Utility. Number 
6 appears only if exécuting in Test mode, since there is no Front End. 
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For live or simulated mode Intercomm, two additional entries are an F2 
log code (HT) when the message is queued for the Front End via FESEND 
(appears in place of the 40 log entry between the 30 and FA entries), 
and an F3 log code (HO) when the message was transmitted by the Front 
End. Logging of the message to be transmitted (log code F2) occurs 
before final Front End processing (idles insertion, New Line to SBA 
sequence conversion, etc.). 


If Message Mapping is used and the message is passed to the Front 
End via FESEND (Figure 8), only the log entries numbered 1, 2, and 4 
appear for each message processing thread, with the FESEND log entry 
(log code 40 or F2) appearing in place of log entry 3. Log entries 3, 
5, and 7 represent the additional processing for a message passed to 
the Output Utility (receiving code U). 


MSGCOL MONITOR 
log code O01 log code FA 
HT HO 


MONITOR MONITOR 
log code 30 log code 30 
HO HO 


APPLICATION FESEND 
OPTIONAL log code log code 
41-6F HT 
HT 


MSGCOL MONITOR 
log code 01 log code FA 
HT HO 


HT = Intercomm message header and message data 
HO = Intercomm message header only 


Figure 10. Sequence of Log Entries 


Figure 11 describes all the Intercomm log codes. Note that user 
log entries may only use log codes in the range X'41' to X'6F’. 
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Internal /External 
Code Format peer tee 


Internal Code: 
External Code: 


Format: 
Restart Use: 


Checkpoint Record 


Message queued for subsystem 
by Front End or a subsystem 


Message restarted through LOGPROC 
the system 


Message restarted--related LOGPROC 
to Data Base Recovery 


Message passed to subsystem Subsystem 
for processing Controller 


Message passed to Front End FESEND 
(test mode only) 


Message restart finished: 
all subsequent log entries 
produced by live Intercomm 


Region started (Multiregion 
only) (Text=Region-id(s)) 


Log code in core during processing (snaps and dumps) 

Log code after translation by LOGPUT (INTERLOG printout) 
HT for header and text, HO for header only 

Yes, No, User (specified via user-coded system macros) 


Figure 11. INTERLOG Entries (Page 1 of 2) 
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Message lost (Region/Hold Q 
full) or flushed (SR/SS down) 
Sign on/off processing, 
security violation messages 


Normal message complete 


Subsystem 
Controller 
Unprocessed message--invalid Message 
subsystem/QPR code Collection 
Unprocessed message--core and Message 
disk queue full Collection 


Subsystem 


Message cancelled--program 
error, time-out or I/O error; 
or flushed by command (Rel 10) 


Message flushed by Retriever, Retriever 
used when application program 
does not obtain (via GETSEG) 
all parts of a segmented 
message; or message failed 
security check SYCT400 
Message after verb USRBTLOG 
verification (optional) 


Message queued for 
transmission 
Message transmitted, 

discarded (MSGHUSR=Z - Rel 10), 
or flushed (MSGHUSR=F - Rel 10 
3270 output message content 
invalid--message dropped. 
Transmitted DDQ msg status: 
see SNA Term. Support Gd. 


Intercomm Restart Accounting 


Figure 11. INTERLOG Entries (Page 2 of 2) 
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ADDITIONAL APPLICATION PROCESSING FACILITIES 


In addition to the application programming facilities described 
in this and related manuals, the application designer should be aware 
of the following processing options available under Intercomm: 


Off-line batch region execution: the Intercomm File Handler, 
DFA, DDQ, Store/Fetch and MMU may be executed by an off-line 


program (coded as non-reentrant) to prepare a file, data 
strings, or messages for on-line access. See the associated 
manuals for linkedit considerations. 


Multiregion Facility batch region interface: when executing 


an on-line Multiregion system, any batch application region 
May pass a message or a FECMDDQ (see also Chapter 9) to an 
on-line subsystem or to the Front End via the Output Utility 


subsystem. See Multiregion Support Facility. 


Time controlled processing: instead of being triggered by an 
input terminal message, an application may be designed to 


execute at a particular time of day. See the Operating 
Reference Manual. 


Segmented input message processing via DDQ: segmented input 


messages, whether gathered by Intercomm from a remote device 
(CPU, etc.) or generated by an application program, are 
placed on a DDQ and may be serially passed to an application 
subsystem via a DDQ Facility interface. See Dynamic Data 


Queuing. 


Dynamic linkedit feature: dynamically loaded user subsystems 
and subroutines are linkedited to called Intercomm resident 
routines at startup, thus reducing the size of the load 
modules. The LOAD system control command is used to force a 
relinkedit of a new version of a dynamically loaded program 
placed on the load library while Intercomm is executing. See 


the Operating Reference Manual. 


User exits: various user exits for installation dependent 
processing are listed in the Operating Reference Manual. 


Binary table search: service routines for incore table 


searching are described in the Assembler Language Programmers 
Guide. 


IJKPRINT: service routine to write one or more print lines 
to SYSPRINT (SYSOUT data set). See the Operating Reference 
Manual. - 


ILJKDELAY: service routine to request a timed delay 
(averaging 100 milliseconds) of program processing, to allow 
other work (subsystem threads) to process. See the Operating 
Reference Manual. 
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3.1 PROGRAM STRUCTURE 


An application subsystem executing under Intercomm control is 
activated to process one message. The following examples typify the 
concerns of message processing logic: 


1. Interpretation of message text to reroute administrative data 
to another terminal. 


2. Editing of message text, creation of a record on a sequential 
data set for later off-line processing and preparation of an 
acknowledgement message to the originating terminal. 


3. Editing and analysis of message text to determine file 
retrieval and/or update criteria, data file access, 
preparation of a response message for the operator at the 
originating terminal. 


4. Analysis of an application-oriented control message and 
appropriate action, such as checking batch totals from 
example 2, above, or acting on a special request to close a 
file or perform some other control function. 


All subsystems are called by Intercomm and execute as subroutines 
with standard parameters passed on entry to the program. Although the 
PL/1 subsystem is a subroutine to Intercomm, it should be defined as a 
MAIN procedure in the PL/1 environment. The parameters must be defined 
to the PL/1 subsystem in the following order: 


1. The input message to be processed (42-byte header plus 
message text) of maximum length 4096 bytes. 


2. The System Parameter Area table (a 500-byte internal table 
plus appended user fields, if any), of maximum length 4096 
bytes. Only the user fields may be modified, if desired. 


3. The Subsystem Control Table entry for the called subsystem (a 
100-byte table entry). This may not be modified. 


4. A fullword arithmetic variable (FIXED BIN(31)) into which the 
subsystem must place an appropriate Intercomm return code 
before returning control to Intercomm. 


The first three of these parameters may be defined as character 
strings or as pointer variables (address of Locator/Descriptors for 
simple character string areas in parameter list), or as dummy 
arithmetic variables which actually are the addresses of the character 
strings, depending on the coding of the SYCTTBL macro PLILNK parameter 
(see Section 3.7 for further details). 
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Figures 12 and 13 illustrate a reentrant PL/1 subsystem with 
parameters defined as pointer variables (most common and easiest 
usage). A precise definition of the System Parameter Area (SPA) and 
Subsystem Control Table entry (SCT) is only required if these table 
areas are referenced by the subsystem during processing. If so, the 
parameters would be declared as structures defining the individual 
fields within the table areas as required by the subsystem. Structures 
defined for the IN_MSG and OUT_MSG areas would be required to assist 
with message manipulation: for this purpose, a member called PLMSGHD is 
provided, which declares the fields of the Intercomm message header as 
level 5 entries within a structure (see Figure 17). 


EXAMPLE]: PROC (INMSG_PTR,SPA_PTR,SCT_PTR, ICOM RC) 
OPTIONS (MAIN, REENTRANT) ; 
DEFINE THE PASSED PARAMETERS: 
(INMSG_PTR,SPA_PTR,SCT_PTR) POINTER; 
IN_MSG CHAR(4096) BASED INMSG_PTR; /* INPUT PARM 1 
SPA CHAR(500) BASED SPA_PTR: /* INPUT PARM 2 
SCT CHAR(100) BASED SCT_PTR; /* INPUT PARM 3 
ICOM_RC FIXED BIN(31); /* INPUT PARM 4 
DEFINE STATIC STORAGE AREAS: 
THESE AREAS SHOULD HAVE THE INITIAL ATTRIBUTE 
AND NOT BE MODIFIED. 


VMI_57 BIT(8) ALIGNED INIT(‘01010111’) STATIC; 
RSC_OUTPUT BIT(8) ALIGNED INIT('11100100' ) STATIC; 
RSCH_OUTPUT BIT(8) ALIGNED INIT(’11100100' ) STATIC; 
FILE_NAME CHAR (8 ) INIT('MYFILE ') STATIC; 


DEFINE VARIABLE STORAGE AREAS: 
THESE AREAS WILL BE DEFINED IN AUTOMATIC STORAGE 
AND WILL BE ASSIGNED FROM THE PROVIDED ISA. 
THERE WILL BE ONE SET OF AREAS FOR EACH MESSAGE 
THREAD INVOKED. 


OUT_MSG CHAR (2048) ; /* OUTPUT MSG 
I,J FIXED BIN(15); /* COUNTERS 
FILE_RECORD_AREA CHAR (200) ; /* READ AREA 
ICOM_RETURN_VALUE FIXED BIN(31); /* RETURN CODE*/ 


NOW DEFINE PROCESSING PROGRAM LOGIC. */ 


*/ 
1 MAINLINE: DO; 
ICOM_RC = 0; /* INIT THE INTERCOMM RETURN CODE */ 


Program Processing Logic 
ICOM_RC = ICOM_RETURN_VALUE; /* SET ICOM RETURN CODE */ 


RETURN; 
END EXAMPLE1; 


Figure 12. Reentrant PL/1 Subsystem Structure 
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INTERCOMM 
SYSTEM 


REENTSBS 
LANGUAGE 
INTERFACES 


SUBSYSTEMS 


REENTRANT 
PL/1 SUBSYSTEM BB 


STATIC STORAGE 


CONSTANT ITEMS 


». 
a 


————14A RET-COD 


INTERCOMM DYNAMIC POOL STORAGE SUBPOOLS 
(aa) BB INPUT BB INPUT 
MESSAGE A MESSAGE B FILE 
AREAS 
(4a) RET-COD A RET-COD B 


ISA For ISA For 
SUBSYSTEM BB SUBSYSTEM BB 
Thread A: Thread B: 


Automatic Variables: Automatic Variables: MVS ACCESS 
OUTPUT MSG. OUTPUT MSG METHODS 
RECORD AREAS RECORD AREAS 
DATA ITEMS DATA ITEMS 


Figure 13. Reentrant Application Program Environment. 
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After a subsystem completes processing and returns control to the 
Subsystem Controller (see Chapter 2), the Intercomm return code is 
checked to determine whether the message should be cancelled due to an 
error. Then the return code is placed in the externally saved input 
message header in MSGHRETIN (MSGHCON+1), and the header is logged with 
an appropriate log code (see Chapter 2). Figure 14 describes Intercomm 


return codes. If the subsystem (or a called subroutine) program 
checks, or the return code is 8 or 12, USRCANC returns an appropriate 
error message to the terminal operator. USRCANC is a user exit 


provided by Intercomm under the name PMICANC, and is described in the 
Operating Reference Manual. 


Unrecoverable error 
condition (no core, 
MAPEND error, etc.) 


(Not used, reserved) 


User codes to identify 
unusual condition 


File or DBMS Update 
Subsystem, no message 
restart required* 


File or DBMS Inquiry 


Subsystem, message 
restart required* 


Force Backout-on-the-Fly* File updates or additions backed ou 


*See File Recovery Users Guide or Data Base Management System 
Users Guide 


**Used only when a called Assembler Language subroutine (MSGCOL/FESEND) 
has requeued or freed the input message. If MAPIN has been called and 
has freed the input message, a return code of 0 must be used. . 


Figure 14. Intercomm System Return Codes 
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3.2 MESSAGE PROCESSING CONCEPTS 


The application program receiving the message may analyze the 
Verb Message Identifier (MSGHVMI) in the header and/or message text 
fields to further control message processing logic. The meaning of 
different VMI values is dependent on the design requirements of the 
program receiving the message. For example, the Front End sets the VMI 
to X'00' to indicate to the Subsystem Controller that editing by the 
Edit Utility is required, based on the specification in the Front End 
Verb Table for a given verb (BIVERB macro, EDIT parameter). The PREPLI 
interface routine then analyzes the VMI to determine if the Edit 
Utility should be called prior to passing the message to the subsystem 
(if editing is successful). A VMI value of X’'FF' (high-values) 
indicates that no processing is required by, or was performed by, the 
Edit Utility. Any other value in the VMI indicates that the Edit 
Utility has already processed the message or that a user subsystem has 
placed a code in the field before switching (queuing) the message to 
the currently processing subsystem. 


An application subsystem creates an output message by building a 
42-byte header and appropriate message text. This new message is 
either passed to the Front End via FESEND for transmission to the 
terminal, or is queued for later processing by the Output Utility or 
some other subsystem by calling the Intercomm system program COBPUT. 
The subsystem destined to receive this new message is determined by the 
receiving subsystem code fields (MSGHRSC, MSGHRSCH) in the message 
header. The receiving subsystem may then analyze the VMI, as 
appropriate. The Output Utility, for example, analyzes the VMI to 
determine whether or not prespecified output message formatting is to 
be performed. If the output message is passed directly to FESEND, 
MSGHRSCH and MSGHRSC should be set to binary zeros (low-values). 


Subsystem logic for input message text analysis and output 
message text creation varies, depending on whether Message Mapping or 
the Edit and Output Utilities are used. Figures 15 and 16 illustrate 
subsystem processing logic for these two cases. 


It is very important to note that the input message area 
(Intercomm header and message text) may only be examined (treated as a 
read-only area) by the application program. It may also be copied to 
an output message area (header only, or header and text) where it may 
be added to or changed, depending on program logic. Never add data to 
the input message text area. 
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Comments 


The subsystem determines (perhaps based 
on the particular verb entered) if the 
input message requires mapping. 


MAPIN is called to convert the input 
message to text consisting of fixed 
length fields with a three-byte prefix of 
length (two bytes) and flag (one byte), 
indicating the result of field conversion. 
All terminal-dependent characters are 
removed. 


Processing logic is application-dependent. 


Output text data has a format similar to 
mapped input text: fixed length data 
fields with a three-byte prefix of length 
(two bytes) and attribute (one byte), 
indicating terminal-dependent field 
characteristics, if applicable. 


MAPOUT is called to build an output 
Message text stream, padding, justifying 
and/or converting data fields from 
arithmetic form, as necessary, and 
adding constant heading information as 
required. 


MAPEND is called to return the output 
message (header and text) in terminal- 
dependent format ready for transmission, 
or to dispose of the output message. 


FESEND is called to pass the output 
message to the Front End (if MAPEND has 
not disposed of the output message). 


Subsystem completes its processing and 
returns to Intercomm. 


Figure 15. Subsystem Logic Using Message Mapping Utilities 
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Subsystem Logic Comments 


ENTRY 
If the Front End Verb Table indicates EDIT=YES, 


Initial- the subsystem receives an edited input message 
ization automatically. The message text consists of fixed 
Logic length data fields or variable length data fields 
prefixed with a l-byte identification and a 1-byte 

length code (binary values). 


Processing Processing logic is application-dependent. 
Logic 


The subsystem prepares an output message by 
creating a message header and the appropriate 
text. Output message text fields are either 
fixed length data fields or variable length 
fields with a prefix as described for Edit, above. 
Message header fields RSCH, RSC, and VMI identify 
the specific message text format. 


COBPUT 


queue the COBPUT is called to queue the output message for 
message for processing by the Output Utility subsystem. 
Output 


Final Subsystem completes its processing and returns to 
Processing Intercomm. 


RETURN 


Figure 16. Subsystem Logic Using Edit and Output Utilities 
(Page 1 of 2) 
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Subsystem Logic Comments ) 


Output Utility The Output Utility performs message formatting 
message for- according to user specifications, adding constant 
Matting logic heading information as required. 


put message FESEND is called to pass the output message to the 
in terminal Front End. Output completes its processing and 
queue returns to Intercomn. 


Figure 16. Subsystem Logic Using Edit and Output Utilities ) 
(Page 2 of 2) 


3.3 SUBSYSTEM CODING 
The language interface routines are: 


e PREPLI--which interfaces the Subsystem Controller to the PL/1 
subsystem by initializing the reentrant environment for each 
subsystem processing thread. If the VMI of the input message 
is X'00’, the Edit Utility is called to edit the message. If 
successful, the subsystem is activated. If unsuccessful, EDIT 
returns an appropriate error message to the input terminal 
and PREPLI returns to the Subsystem Controller (subsystem not 
activated). If the subsystem is loaded above the 16M line 

-under XA or ESA, it will receive control in 31l-Amode. 


PREPLI optionally supports the PL/l execution parameters 
STAE, SPIE and REPORT. FLOW, COUNT, HEAP and TEST (PL/1 V2)y. 
are not supported. By default, SPIE and STAE are not used so 
that Intercomm recovery code receives control and allows the 
on-line system to continue execution (NOSPIE option), or to 
gracefully clean up (NOSTAE option) after an abend. The 
REPORT option is useful only in a test environment to 


determine the total ISA needed for subsystem execution. To 
use the REPORT option, a DD statement for the PLIDUMP ‘ 
(SYSOUT) data set (not SYSPRINT) must be added to the ) 


Intercomm execution JCL (after the PMISTOP DD statement); see 
the Operating Reference Manual for option implementation. 
38 


Chapter 3 Coding an Intercomm 
Subsystem in PL/1 


e PLIV--a ‘top hat’ linked with loaded PL/1 subsystems to 
provide entry points (PLICALLB and subsystem program code via 
PLIMAIN) to PREPLI. See Appendix A for loaded subsystem 
linkedit. 


e INTLOAD--linked with dynamically loaded PL/1 programs to 
provide Intercomm service routine and user subroutine 
linkage, especially if program loaded above 16M line. 


e PMIPL1--optional interface, which maintains linkages and save 
areas (and performs Amode switching under XA or ESA), from 
PL/1 programs to Intercomm service routines and/or to user 
subroutines (resident or dynamically loaded). PMIPL1 
preserves the multithreaded reentrant PL/1 environment while 
providing a standard CALL interface to the routines. Note 
however, that all parameters passed to PMIPL1 (except as 
noted in Appendix D) must be character data (cannot have 
arithmetic attributes). 


@ COBPUT--which is called via PMIPL1, or directly, to copy a 
message from the automatic storage of a PL/1 program into the 
Intercomm-managed dynamic pool storage area before passing it 
to Message Collection to be queued for another subsystem. 


@ REENTSBS--table of Intercomm service routine and user-coded 
subroutine entry points, names and related characteristics. 
(Required if PMIPL1 is used). 


PL/1 subsystems may directly call Intercomm service routines and 
user subroutines using standard CALL statements, by declaring the 
routines as ENTRY OPTIONS (ASM INTER). A member PLIENTRY, listed in 
Appendix B, provides such declarations for the most commonly used 
Intercomm service routines. PLIENTRY may be copied into the PL/1 
program via a %INCLUDE statement. User-coded PL/1 subroutines may also 
use this same interface scheme. 


If the routines are not called directly, then one routine only is 
called: PMIPL1, which is declared as ENTRY EXTERNAL. The first passed 
parameter is the name of a code defining the actual routine to which 
interface is desired, subsequent parameters are those required by the 
called routine, and must be in Automatic Storage if the subsystem 
(subroutine) can be loaded above the 16M line (must be a 24-bit 
address). Coding format: 


CALL PMIPL1(routine-code,parml[,parm2,...]); 


Subsequent chapters of this manual, and of related message processing 
facility manuals, contain detailed descriptions of applicable 
routine-code names and the parameters required for each routine. The 
Intercomm source text member PENTRY, listed in Appendix B, provides the 
definition of the halfword routine-code constants (FIXED BIN(15)) used 
for calling most of the Intercomm service routines via PMIPLIl. To 
ensure that the correct code value is used, PENTRY should be copied 
into the static storage section of each PL/1 program using a %INCLUDE 
statement. Routine-code names correspond to the entry point name 
defined in REENTSBS, and the code itself is an index value (offset) 
into the REENTSBS table (see Chapter 9). 
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For calls to other Intercomm service routines and for user 
subroutines, add the names and index values to PENTRY and add 
corresponding entries to the REENTSBS table (see Section 9.1) if the 
PMIPL1 interface is used, or add the names to PLIENTRY, if the routines 
are called directly. User subroutine interface is further described in 
Chapter 9. 


Figure 17 illustrates the basic coding required to implement an 
Intercomm subsystem and the definition of an input message and creation 
of an output message via an application to "“echo" the text of an 
incoming message back to the originating terminal. The Message Mapping 
Utilities, the Edit Utility and the formatting capabilities of the 
Output Utility are not used. Note that the input parameters are 
declared as simple character strings. 


1. The message header is created by copying the input message 
header to the output message header area and adjusting the 
following fields: 


e MSGHSSCH, MSGHSSC--Sending Subsystem Code 


Move in the original receiving subsystem code values, 
MSGHRSCH (to MSGHSSCH) and MSGHRSC (to MSGHSSC), to 
identify the current subsystem as the sending subsystem. 


e MSGHRSCH, MSGHRSC- -Receiving Subsystem Code 


Move in a predefined code to indicate further processing 
(the next subsystem) for this message (for FESEND, use 
binary zeros - null bit string). 


e MSGHVMI--Verb/Message Identifier 


Move in a predefined code for subsystem processing, or toa 
indicate to FESEND that the output message is not fully 
formatted, use X‘'57'. If an output message is formatted 
by MMU, do not touch this field. 


e _MSGHLEN- -Message Length 


Modified to include header and text length of output 
message. 


e MSGHTID--Receiving Terminal Name 
If the originating terminal is to receive the response 


Message, do not change. Otherwise, specify the receiving 
terminal name for the output message(s). 
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2. The new message text is created by copying the input message 
text to the output text area, and then appending the author’s 
name and a message ending character (X'’26’ or X'37'). 


3. Queuing of the output message for the terminal is 
accomplished via the service routine FESEND (FESENDC). 


4. The return code from the queuing routine must be analyzed to 
assure that the new message was actually queued, and recovery 
action taken if not. 


5. The last logical activity in the subsystem is to give a value 
to the Intercomm return code field and return to the 
Subsystem Controller. 


The procedure entry point name must correspond to the subsystem 
entry point (load module name) described in the Subsystem Control 
Table. 


The input-message entry parameter has been further defined to 
reference the 42-byte input message header and the input message text 
as separate entities. See Chapter 2 for a description of individual 
fields in the message header as detailed for the output message area 
(see comments in the sample program). 


To assist the programmer in defining the message header, there is 
a source text member, PLMSGHD, listed in Appendix B. This member may be 
ZINCLUDE'd within a structure defining the input and/or output message 
areas and is defined to declare level 5 entries within the structure. 
If the input message area is declared as a character string as in the 
sample program, a structure may not be used to detail areas of the 
message; only DEFINED statements may be used as illustrated in the 
sample program (to prevent program execution errors). A structure may 
be declared for the input message if the parameter is defined as a 
pointer (see Figure 12) and the structure is BASED on the pointer. 


The entry parameters for the System Parameter Area (SPA) and 
Subsystem Control Table entry (SCT) for the subsystem are not detailed 
as there is no need to reference any of their individual fields. 


The entry parameter for the Intercomm return code is used to 
indicate the result of message processing to the Subsystem Controller. 


Constants are defined as STATIC items with the INITIAL 
attribute. All variables, and constants that may be passed as 
parameters, should be defined in (moved to) automatic storage, so that 
they are given unique areas for each message thread that is being 
processed. The allocation of automatic storage is done out of the ISA 
provided by the PREPLI interface routine, based on the SPAC parameter 
defined on the subsystem’s SYCTTBL definition (see Chapter 2). 
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3.3.1 Message Switching Between Subsystems 


Any Intercomm subsystem may send a message to any other Intercomm 
subsystem. If a message is sent to some other subsystem, it is called 
"message switching." An application subsystem can switch a message to 
the Output Utility, which is another subsystem. The Change/Display 


Utility switches messages to the Output Utility. An application 
subsystem may switch (or requeue) a message to itself in the event that 
reprocessing or deferred processing of the message is required. An 


application subsystem may exceed an installation’s core limitations and 
be broken into several subsystems. One subsystem may receive a message 
input from a terminal, perform partial processing and develop 
intermediate results in the form of a message sent to a_ second 
subsystem. The second subsystem processes the intermediate results as 
an input message and may complete the message processing or develop 
additional intermediate results in the form of messages sent or 
switched to any other subsystem or subsystems. Any one of these 
subsystems might also switch messages to the Output Utility. 


Message switching between subsystems is accomplished by moving 
the input message to an output message area and then changing the 
receiving subsystem code in the header and calling COBPUT as usual. 
The Verb/Message Identifier (MSGHVMI) may be initialized for 
interpretation by the receiving subsystem. A VMI equal to X'‘00’ 
indicates that the Edit Utility is to be called by PREPLI prior to 
activating the receiving PL/1 subsystem. 


To switch messages between terminals, the destination terminal 


identifier (MSGHTID) would also have to be changed before calling 
COBPUT or FESEND. 
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STAT LEV NT 
1 QO ECHOPL1: PROC CINIMSGySPAySCTy»ICOM_RC) 
OPTIONS (MAIN yREENTRANT)§ 
/* DECLARE FIRST THREE PARAMETERS AS CFARACTER STRINGS +/ 
2 2 0 DCL 2 IN_LMSG CHAR (542) 9 /* INPUT PARM 1 *#/ 
INLHDR CHAR(42) CEFINED INLPSG, 
INL TEXT (500) CHAR(1) CEFINEC INLMSG PCSITICN(43)5 
3 2 0 DCL SPA CHAR(500)5 /* INPUT PARP 2 #/ 
4 1 #0 OCL SCT CHAR(100)3 /* INPUT PARM 3 *%/ 
5 21 Oo OCL ICOM_RC FIXED BIN(21); 7* INPUT PARM 4 */ 
6 2 © DCL 1 OUT_LMSG, 7* OLTPLT MSG AREA */ 
3 OUT_HDR CHAR(42) 5 /* TO COPY INLHDR */ 
3 OUTLTEXT(512) CHAR(1)» /* MAX TEXT SIZE */ 
1 OUTLMSG_DEF DEFINED CLILMSGs 
3 OUTLHDkK_DEF, /* TC PROVIDE MSG HEADER VARIABLES */ 


ZINCLUDE PLMSGHD; eee eee nea a ee OOOH EEE RHE R EEE ES ERED E EERE TER ER RED 
MSGRLEN FIXED BIN(15) UNALIGNED, 
MSGROPR CFAR (1), 

MSGHRSCr BIT (8) ALIGNELs 
MSGPRSC BIT (8) ALICKEDs 

MSGFSSC BIT (6) ALIGNED, 

MSGFAMN BIT (24) ALIGNED, 
MSGEDAT CrAR (6), 

MSGRTIP CrAk (8), 

MPSGETID CrAkR (5) 

MSGFCON BIT (16) ALIGNELy 
MSGRFLGS CraR (2)5 

MSGHBMN BIT (24) ALIGNELs 
MSGrSSCh BIT (8) ALIGNEL, 
MSGFUSR CrAK (1), 

MSGRADDk EIT (1e¢) ALIGNECs 
MSGrLUG CFAR (1)9 

MSCGCFBLK BIT (@) ALIGNEDs 

PSGRYMI E1T (&) ALIGNED, 


Wn Un uot toons sooo o> 


ROSS TRTEER ERE EERE 


3 TEXT_DEF(5i2) CHAR(1);3 7> NCT KEFERENCED ¥/ 
4* WOTE? ABCVE USt UF DEFINEC CALSES COPPiLER RETURN COCEKe@ */ 
/* BLT DOES NUT CAUSE LINKEDIT/EXECLTICN PROBLEMS. */ 


Figure 17. Echo Message Example; Reentrant PL/1 
(Page 1 of 4) 
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/* DECLARE CONSTANTS AND AUTOMATIC VARIABLES. */ 


DCL 
DCL 
DCL 


(lyJ) 
CHAR_COUNT 
FESENDC_RC 
FESEND_RC 


PIC'99%, 
CHAR(2) 


FIXED BIN(15)3 
FIXED BIA(31); 


7* COUNTERS INTC TEXT *%/ 
/* ACTUAL TEXT LENGTH *%/ 
/# FESEADC RETLRN CODE */ 


CEFINED FESENDC_RC3 


7* MUST BE Cha&R FCR CALL PMIPLI(FESENDCCoooe) %/ 


CCL AUTHORS_NAME2 CHAR(12) 
AUTHORS_NAME(12) CHAR(1) 
DCL DEFAULT_TEXT2 CHAR (6C) 
XT HAS BEEN PLT IN ITS PLACE") 
DEFAULT_TEXT(00) CHAR(1) 
VMI_57? BIT(8) ALIGNEC 
MSG_END BIT(8) ALIGNEC 
MSG_END_EQT CHAR(1) 

/* "DEFINEC® CF MSG_END CODE 35 
/* SUBRCUTINE CALL TC 
/* NOTE: 


DCL 
OCL 


INITO® = Me DAVIES’) STATIC, 
DEFINEC ALTHORS_NAME2; 
INITC'CRIGIAAL DATA TOC LENG - 
STATIC» 
CEFINEE 
IAIT¢C*C1C10121") 
IN1TC*CC11C0111') 
DEFINEC FSGLEND3 
CHAR SAVES EXTERNAL 
MOVE EIT STKINGe 


TRIS TE 


CEFAULT_TEXT23 
STATIC; 
STATIC, 


ABCVE USE CF DEFINED CAUSES CCMPILER RETURN CODE=8 


/* BUT DOES NOT CAUSE LIAKEDIT/EXECLTION PROBLEMS. 


Figure 17. 
(Page 2 of 4) 
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/* INTERCCPHM INTERFACE */ 


LINCLUDE PENTRY} *#OO Oe ee reese een eee eee Eee RHEE HOSE EEEEE DOOR EERE DRED D 


i¢] DCL 1 PENTRY STATIC, 


2 ( /*1F OFFSET ODDsTRLE CFFSET#=(OFFSET¢1)*/ 


INTSORTC 
DWSSNAP 
MAPFREE 
FECMRLSE 
FESEND 
FESENDC 
ALLOCATE 
ACCESS 
MAPURGE 
MAPCLR 
MAPEND 
MAPOUT 
MAPIN 
INTUNSTO 
INTSTORE 
INTFETCH 
FECMFDbK 
FECMDDt 
OWRITEX 
QREAUX 
OWRITE 
QREAL 
GCLCSE 
COPEN 
Q@BUILD 
SELECT 
RELEASE 
REAC 
WRITE 
GET 
PUT 
RELEX 
FEUY 
CObPuT 
MSGCCL 
COBSTORF 
CONVERSE 
DBIAT 
LOGPLT 
PAGE 
GETV 
PUTV 
FIXED pINt15); 


PPR REP RHEE i* 


Figure 17. Echo Message Example; Reentrant PL/1 
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INIT(SS) 5 
INIT(OG5), 
INIT(S]), 
INIT(CET) 5 
INIT(83)5 
INITO?G) 5 
INIT(75)5 
INITOV1) 5 
INITCE7)» 
INIT(E2)5 
INIT(55)5 
INITCU55),5 
INITCEL), 
IA1T(47), 
INIT(43) 5 
INI1T(39), 
IKIT(BE), 
IAIT(21)5 
INIT TOZ7)» 
IN]T(23), 
TAATO1G) 5 
IAIT(CIS), 
TALTOII1), 
INITE TD), 
IN1TC 3)5 
INITC 4) 5 
INIT @),y 
INIT(1lE) 
INITtle dys 
TAIT¢(EC)y 
TNLT¢&Z4) 9 
INIT(2t) 9 
INIT(32)5 
TRiT(Eet)s 
IA1T(7e)s5 
INIT 7c); 
INIT(CAC)s 
INITCE4) 
TNGTCEEDS 
INIT(S2)s5 
INLT(GE), 
IAIT(1CC) 


) 


/* UPDATE #/ 


/* REL 1C 4/ 
/* REL 1C #/ 


FOR REENTSBS LCLES/ENTRY PCIATS */ 
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STMT LEV NT 


MAINLINE? DG3 
ICOM_RC = 0 5 . /* INIT TRE INTERCOMM RETURN CODE */ 
FESENDC_RC = "Ou! ; /* IKIT TRE FESEROC RETURN CODE */ 
OUT_HDR = IN_LHDR 3 /* INPUT FEACER TG CUTPUT AREA */ 
CHAR_COUNT = BSGHLEK 3} /*# MSG LENGTH TO FULLWOREC COUNTER */ 
CHAR_CCUNT = CHAR_CCUNT - 43 3 /* OFIT HEADER AND EOT */ 
MSGHSSC © MSGHRSC ; /* RECEIVING TC SENDING */ 
MSGHSSCH = MSGHRSCH 3; /*# RECEIVING 10 SENDING */ 
MSGHRSC = ''B j /* CLEAR RECEIVING */ 
MSGHRSCh = '%% j /* CLEAR RECEIVING */ 
MSGHVEI = VMI_57 3 /* SET Vl] CCDE ¥y 
IF CHAR_COUNT > 499 
THEN 
DO I=1 Td 60; 7* WEEN INFLT TEXT 100 LONG 
OUT_TEXT(1) = CEFALLT_LTEXT(12; /* LSE DEFAULT MSG 
END; 
ELSE ; 
DO I=1 TG CHAR_CCUNT; 7* WEEN IKFUT TEXT ¢ 500 
OUT_TEXT(I) @ IRLTEXT(I)$ /* MCVE MESSAGE TEXT 
END; 
DO ssl TC 123 y* ALWAYS = 
OUT_LTEXT(1) = AUTHORS_NAMEGJ)3}  /9 ADD ALTHUR'S NAME 
Ilele*i3 


et se et pe pe Pe 


eee 


END; 
OUT_TEXT(I) = MSG_END_ECT3 7* ANC AUC MESSAGE END CODE 
MSGHLEN = I * 433 /* WEACER*TEXT*ALTHGR_NAME*ECT 
CALL PMIPLI(FESENDC,OUT_PSCyFESENC_RC}; /* QUELE MESSAGE 
IF FESENDC_RC a= "OC! 
THEN 
DC} 


1 
1 
1 
1 
1 
1 
1 
1 
1 
1 


Pere NN Ne 


ICOMLRC = FESEACC_kC; 7 aPEN MESSACE NOT QUELED */ 
END; 
END; 
RETURN; 
EnD ECHOPL1; 


Figure 17. Echo Message Example; Reentrant PL/1 
(Page 4 of 4) 
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( 3.4  PL/1 CODING CONVENTIONS AND TECHNIQUES 


When coding a PL/1 subsystem, there are several PL/1l features to 


consider: 


1. 


ON-units 


These may be used under Intercomm; however, note the 
following: 


a. Do not reference conditions that will be handled by 
Intercomm program check (SPIE/ESPIE) processing (for 
example, CONVERSION, FIXEDOVERFLOW, ZERODIVIDE); nor that 
concerning PL/1 I/0 (for example, ENDFILE, KEY, 
TRANSMIT), all of which are handled by the Intercomm File 
Handler interface. 


b. For a production subsystem, ON-units may incur an 
inordinate amount of overhead - restrict their use to 
debugging, if possible. 


BEGIN-blocks 


Beware of the overhead involved in block initialization 
procedures, both for storage and for processing time. 


RECURSIVE procedures 


Use cautiously, considering storage allocations involved; do 
not call an internal PL/1 procedure from within a called 
procedure, or from within itself. 


ALLOCATE/FREE statements 


Controlled and dynamically allocated based variables should 
not be used unless they can be allocated by PL/1 from the ISA 
supplied by Intercomn. If such variables are used, be 
careful to specify an ISA size large enough to include the 
allocated storage on the SPAC parameter of the SYCTTBL macro 
for the subsystem. 


FETCH/RELEASE statements 


Do not use for dynamic loading of external procedures. 
Instead, CALL them as user subroutines using Intercomm 
controlled interfaces. 


Multitasking 


Don’t. If necessary, call an Assembler Language routine that 
issues a SUBTASK macro (see Intercomm Assembler Language 
Programmer's Guide). 
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7. Data conversion requiring subroutine calls 


Avoid whenever possible (message IELO906I at end of compile): Jd 
check correct syntax on field editing PICTURE patterns, match 

variable definition attributes for simple data moves (when 

arithmetic conversion is not required). Define numeric input 

fields edited by the Edit Utility with PIC ‘...’ clause. 

Define numeric fields in MMU maps to have the same form as in 

the associated file record and let MMU do the editing. 


8. CONVERSION and ZERODIVIDE conditions 


Prevent them by testing fields are numeric before arithmetic 
conversion, and not zero before division. 


3.4.1 XA/ESA Extended Storage Loading Requirements (Release 10 only) 


PL/1 subsystems and subroutines using Intercomm reentrant coding 
conventions are eligible for loading above the 16M line under XA and 
ESA if these recommendations are followed: 


e The module should be linkedited with the AMODE=31,RMODE=ANY, 
NCAL and RENT (or REUS) parameters. 


e For subsystems, the LOADNAM, LANG=RPL1, BLDL=YES (default), 
and REUSE=YES (default) parameters are required on the 
SYCTTBL macro (a loaded subsystem remains in extended storage 
except when necessary to delete it after a program check, -) 
time-out, or by user system control command request). 


e For subroutines, the LNAME, TYPE=PL1, BLDI=YES (default) and 
USAGE=REENT (default) parameters are required on the SUBMODS 
macro defining the subroutine to Intercomm in the REENTSBS 
table (see also Chapter 9). 


© Ensure that the Intercomm interface routines SYCT400 
(Subsystem Controller), PREPLI, PMIPL1, INTLOAD, and DYNLLOAD 
(for loaded subroutines) were reassembled with the XA global 
on in the Intercomm global table SETGLOBE. 


e All parameters passed via direct calls to service routines or 
user subroutines must be in 24-Amode automatic storage 
(DSA). Constants (file names, map names, etc.) must be moved 
to automatic variables in the program’s DSA before the call. 
The location of the parameter addresses is not checked by 
Intercomm for direct calls, however a program check will. 
occur if a 3l-Amode parameter is referenced by a 24-Amode™ 
(resident in Intercomm load module or dynamically loaded) 
progran. : - 


ee All programs issuing direct calls to Intercomm service 
routines and user subroutines must be linked with the 
Intercomm interface routine INTLOAD (see Appendix A) which 
dynamically interfaces with the resident Amode-switching -) 
routine SWMODE which must be in the Intercomm load module. 
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e All parameters (except the PENTRY (REENTSBS) code) passed via 
calls to PMIPL1 must be in 24-Amode automatic storage (DSA). 
Constants (file names, map names, etc.) must be moved to 
automatic variables in the program's DSA before the call. 
PMIPL1 checks all parameter addresses (even those passed to 
user subroutines), and if not a 24-Amode address, PMIPL1 will 
force a program check (ISK 0,1) and therefore not execute the 
call. If only PMIPL1 is called, the loaded program need not 
be linked with INTLOAD as PMIPL1 performs mode-switching. 


e For any calls to user subroutines, whether via PMIPL1 or 
called directly, the user subroutines must be defined via 
SUBMODS macros in the REENTSBS table which must be in the 
Intercomm load module. See Chapter 9 for defining the 
subroutines to INTLOAD when using direct calls (the caller 
must be linked with a modified INTLOAD which contains entries 
for the subroutines in addition to service routine entry 
points). See Appendix A for PL/1 subroutine linkediting. 


3.5 RESTARTED MESSAGES 


After an Intercomm system failure (abend or operator cancel) or 
an operating system failure (requiring a re-IPL of the CPU), Intercomm 
may be brought up in Restart Mode which permits reprocessing of 
messages in progress at the time of failure. Additionally, previously 
cancelled messages (see Figure 14), and unprocessed messages (received 
and queued, but not started) will be requeued for processing after 
system startup completes. This is accomplished by retrieving the 
original input messages from the log created in the previous Intercomm 
execution as described in the Operating Reference Manual, and may be 
coordinated with file or database record backout as described in the 


File Recovery Users Guide and DBMS Users Guide. 


Restarting of messages for a particular subsystem is controlled 
by the RESTART parameter of the SYCTTBL macro defining the subsystem in 


the SCT. A restarted input message (in progress at failure time) 
contains a log code of C’R’ or C’P’ (if data base update may be 
executed by the subsystem). All other input messages contain a log 
code of C’2' (see Figure 11). A subsystem may need a different 


processing path for a restarted message and should be careful about 
creating an output response message which might confuse a terminal 
operator. 


3.6 DWSSNAP_ FACILITY (Release 10 only) 


The DWSSNAP Facility allows a PL/1 subsystem to snap data areas 
from its own DSA; a PL/1 subroutine can snap areas from the calling 
subsystem’s ISA (data areas passed as parameters to the subroutine). 
The output of the DWSSNAP request may be sent to SNAPDD (unlimited 
output) with snap ID=087 or may be returned to the inputting terminal 
(limit is one screen of output per snap, all subsequent pages of output 
are lost), or may be routed to another terminal, usually a printer 
(maximum output of 20 pages). The parameters for the DWSSNAP call are: 
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Contents 


The Snap Control Word, initialized to: ‘PSpp’ 
(SNAP Option) for output to the system SNAPDD 
data set; ‘BD’ (DISPLAY Option) for output 
back to the inputting terminal, ‘'PPPp' (PRINTER 
Option) for output to terminal named in next 


The Intercomm terminal name where output is to 
be routed. Only coded if PRINTER option used. 


A data name in the subsystem’s/subroutine’s DSA 
which represents the start of the area to be 


parm-address-end A data name in the subsystem’s/subroutine’s DSA 
which represents the end (must be a higher 
address than start) of the area to be snapped. 


Coding format: 


CALL DWSSNAP(SNCWname[,term-id] 
[, parm-address-start[ ,parm-address-end] ]); 


The CALL to DWSSNAP can have up to 5 address pairs specified. 
However, no address need be coded if a snap of the entire ISA is 
desired. For example: 


CALL DWSSNAP(SNCWname) ; 
will cause the entire ISA to be snapped. 
CALL DWSSNAP(SNCWname , parm-address-start); 
will cause a snap of DSA from parm-address-start to the end of the ISA. 


NOTE: the PL/1 compiler does not place data fields in the DSA in the 
order coded. Use the map of the DSA to determine delimiters when 
using address pairs, or insert a dummy field to provide an 
address-end label as in the subroutine example below. 


When using the DWSSNAP Facility to receive output at the 
inputting terminal, data areas to be snapped (all inclusive) cannot 
exceed 300 bytes (only one page of output will be sent to the inputting 
terminal; all additional output will be ignored/lost) when one pair of 
addresses is specified. If multiple address pairs are specified then” 
the number of bytes that can be snapped is 300 minus 48 (times the 
number of address pairs desired). The storage snapped will be- 
displayed at the terminal just as it would appear in a formatted dump; 
hexadecimal digits (to the left) and the alphanumeric equivalent (to 
the right). 
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When calling DWSSNAP from a PL/1 subroutine, the addresses passed 
to DWSSNAP as parms must be within the ISA of the main PL/1 subsystem. 
To pass addresses in the ISA of the subsystem from a subroutine, they 
must be part of the input parameters to the subroutine. For example: 


SUBRTN: PROC (RECORD_PTR) OPTIONS (REENTRANT) ; 
DCL RECORD_PTR POINTER; 
DCL 1 RECORD-AREA BASED(RECORD_PTR), 
4 RECORD CHAR (166), 
4 RECORD_END_FILLER CHAR(1); 
DCL 1 SNCW CHAR(4); 


SNCW = 'PD}P'; 
CALL DWSSNAP(SNCW,RECORD, RECORD_END_FILLER) ; 


will cause a snap, to the inputting terminal, of the 166-character 
Record-Area passed to the subroutine by the subsystem as a parameter, 
provided the output does not exceed one screen (everything in excess of 
one screen will be lost). RECORD_END_FILLER is a delimiter for the 
snap. 


3.7 BASED VERSUS NONBASED_ PARAMETERS 


The PLILNK parameter of the SYCTTBL macro defining the subsystem 
to Intercomm specifies whether PREPLI will pass the first three 
parameters to the subsystem as pointer variables or character strings 
(PLILNK=NONBASED) for which the addresses of Locator/Descriptors for 
simple character strings are in the parameter list, or whether the 
parameters are passed as arithmetic variables which are the actual 
addresses of the areas as for Assembler Language programs 
(PL1LNK=BASED) . 


As seen in Figure 12, the default method of receiving the 
parameters to a PL/1 subsystem is as pointer variables, or as 


illustrated in Figure 17 as simple character strings. If using 
pointers, these areas may be defined as structures to enable individual 
data items within a parameter area to be referenced. If the first 


three parameters are pointers, the character strings or structures are 
defined as BASED upon the passed parameters as illustrated in Figure 


12. Figure 17a illustrates a version of Figure 12, and shows the 
passed parameters defined as arithmetic variables (FIXED BIN(31)), that 
is, they are the actual addresses of the parameter areas. Again, the 


parameter areas are BASED upon the incoming parameters, however, it is 
necessary to set up each arithmetic variable as the character string 
address as illustrated in the MAINLINE code for the input message. 


Declaring the input parameters as POINTERs is the easiest to use 
as a structure may be defined on each BASED pointer and the declaration 
is valid for message header reference and input parameter reference for 
direct calls and calls via PMIPL1. When declared simply as character 
strings, they may not be defined as structures (invalid data item 
references occur). When declared as arithmetic variables, addressing 
must be declared, and if MAPIN is called directly, six parameters must 
be passed (as though PMIPL1 was being called with the code for MAPIN as 
a seventh parameter) and the mapped input area may not be a BASED area. 
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EXAMPLE2: PROC (IN_MSG_ADDR,SPA_ADDR,SCT_ADDR, ICOM_RC) 


OPTIONS (MAIN, REENTRANT) ; 
DEFINE THE PASSED PARAMETERS: 

IN_MSG_ADDR FIXED BIN(31); 

SPA_ADDR FIXED BIN(31); 

SCT_ADDR FIXED BIN(31); 

ICOM_RC FIXED BIN(31); 

IN_MSG CHAR(4096) BASED(IN_MSG_PTR); 


DEFINE STATIC STORAGE AREAS: 


/* 
/* 
/* 

* 


/* 


INPUT PARM 1 
INPUT PARM 2 
INPUT PARM 3 
INPUT PARM 4 
INPUT MSG 


THESE AREAS SHOULD HAVE THE INITIAL ATTRIBUTE 


AND NOT BE MODIFIED. 


VMI_57 BIT(8) ALIGNED INIT(‘01010111') 
RSC_OUTPUT BIT(8) ALIGNED INIT(’11100100' ) 
RSCH_OUTPUT BIT(8) ALIGNED INIT(‘11100100' ) 
FILE_NAME CHAR (8) INIT(‘MYFILE ‘) 


DEFINE VARIABLE STORAGE AREAS: 


STATIC; 
STATIC; 
STATIC; 
STATIC; 


THESE AREAS WILL BE DEFINED IN AUTOMATIC STORAGE 
AND WILL BE ASSIGNED FROM THE PROVIDED ISA. 
THERE WILL BE ONE SET OF AREAS FOR EACH MESSAGE 


THREAD INVOKED. 
OUT_MSG CHAR (2048) ; 
rd FIXED BIN(15); 


FILE_RECOND_AREA CHAR (200) ; 
ICOM_RETURN_VALUE FIXED BIN(31); 


NOW DEFINE PROCESSING PROGRAM LOGIC. 


MAINLINE: DO; 


/* OUTPUT MSG 
/* COUNTERS 

/* READ AREA 

/* RETURN CODE*/ 


ICOM_RC = 0; /* INIT THE INTERCOMM RETURN CODE 
IN_MSG_PTR = ADDR(IN_MSG_ADDR) ; /* SET PARM AS ADDRESS 


Program Processing Logic 


ICOM_RC = ICOM_RETURN_VALUE; /* SET ICOM RETURN CODE 


RETURN ; 
END EXAMPLE2; 


Figure 17a. Reentrant PL/1 Subsystem Structure 
using BASED arithmetic variable parameters. .- 
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4.1 CONCEPTS 


The Message Mapping Utilities (MMU) provide an interface between 
the application subsystem and terminal-dependent message processing 
logic for both input and output messages. MMU is invoked by calls to 
Intercomm service routines which perform mapping functions based upon 
user-specified tables (MAPs). Mapping includes justification, padding, 
and conversion of character data to/from arithmetic format. 


4.2 PROCESSING 


MMU input mapping produces fixed length data fields prefixed by a 
two-byte length and one-byte flag (indicates errors or omissions) 
unless the data fields are defined in a structured (named) segment 
(contiguous group of fields). In this case the three-byte prefix 
occurs for the entire segment, not for the individual fields. 


MMU output mapping operates upon data in the same format, but the 
flag byte becomes the field (or segment) attribute character. The 
mapped input text area and the unmapped output text area are called 
symbolic maps and are defined by “INCLUDE statements in the application 


program’s dynamic storage area (automatic storage). The application 
program references data fields and the associated prefix by symbolic 
name. For example, a customer name field (CUSTMER) of twenty-five 


characters would appear within an MMU symbolic structure definition as 
follows: 


4 CUSTMERL FIXED BIN(15), (length) 
4 CUSTMERT  CHAR(1), (flag/attribute) 
4 CUSTMER  CHAR(25), (data) 


When defining maps for use by PL/1 subsystems, there is a special 
parameter, BASED, to be coded to indicate for symbolic map area 
generation whether the map area is (YES - default) or is not (NO) to be 
based on a pointer (PTR_mapname). If YES is coded, the symbolic map 
area for input message mapping may be acquired by MMU (requires a 
direct call to MAPIN with 5 parameters) and it replaces the input 
message area which was also based on a pointer (requires 
PLIINK=NONBASED on subsystem SYCTTBL). The map area pointer is 
initialized after the MAPIN call and the acquired area is freed before 
RETURN to the Monitor as in the sample program in Chapter 10. When NO 
is coded, symbolic map areas are in the DSA. 


Output message disposition is determined by options passed to 
MMU: the formatted message(s) may be returned to the subsystem; passed 
to FESEND for terminal queuing; passed to the Page Facility for CRT 
page browsing; or spooled to a DDQ for subsequent transmission as a 
series of report pages for a printer. A summary of message processing 
logic using MMU is shown in Figure 18. For a complete description of 
Message Mapping and its use by application subsystems, refer to the 


Intercomm Message Mapping Utilities. 
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APPLICATION SERVICE 
LOGIC ROUTINES 


MAP 


Initiali- Load 
zation Modules 


Prepare LOADMAP 
MAPIN Offline 
Calling Utilit 


Process 
Mapped Convert/Edit 
Input 
Message 


Prepare MAPOUT 


= 
Calling Message Data 
s 


lessage 
Finished 


YES 
Prepare 
MAPEND 


Calling 
eq Cc 


Convert /Edit 
Output 
Message 


Figure 18. Message Processing Using MMU 
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5.1 GONCEPTS 


The Edit Utility may be used for input messages instead of MMU. 
It provides an interface to facilitate application program logic for 
message editing. When editing has been requested for a verb (via Front 
End Verb Table specification), the Intercomm -PREPLI interface program 
calls the Edit Utility to produce edited message text from data fields 
entered by the terminal operator. 


The edited message becomes the input message passed to the 
subsystem. The Edit Control routine strips the following field 
definition characters during the course of editing: 


e The system separator character, as defined in the System 
Parameter List (SPA) 


e 3270 CRT SBA sequences 

e Dataspeed 40/1 and 2 terminal TAB characters 

e@e New Line characters 

e Carriage Return or combined Carriage Return/Line Feed 


© End of Text, End of Message, End of Block, or End of 
Transmission characters. 


All other device control characters not translated or otherwise 
suppressed by the Front End translation table for a particular device 
will be treated as text within a field. 


Editing is controlled by the Edit Control Table (ECT - system 
table PMIVERBS), which contains all information about each message 
necessary to perform editing. An edit proceeds field by field based 
upon the user-specified ECT. Data fields may be edited by Intercomm or 


user-coded Edit Subroutines. For a complete description of the Edit 
Utility, its components and processing logic, refer to the Intercomm 
Utilities Users Guide. The sample program in Chapter 12 illustrates 


edited message processing. 


5.2 PROCESSING RESULTS 
The result of processing by EDIT is a message with a standard 


forty-two-byte message header and data fields in one of the following 
basic formats: 
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e Fixed Format ) 


Each edited field is of fixed length in a predefined sequence 
as follows: 


DATA] DATA | DATA 
1 2 N 


e Variable Format 


Each edited field may vary in length and position in the 
edited result. Each edited field is prefixed with a one-byte 
identification code, one-byte length, and possibly a one-byte 
occurrence number for fields defined as repetitive in the 
ECT: 


DATA DATA DATA 
HEADER| I} L X I] L Y IT] L Z 


The Edit Utility considers a message successfully edited if there 
are no required fields (as specified by the Edit Control Table) in 
error or omitted. In the case of unsuccessful editing, Edit sends an 
error message to the originating terminal for each required field 
omitted or in error. If none of the required fields is omitted or in 
error, it remains the responsibility of the application program to 
analyze the edited result and perform recovery logic for any non- wae 
required fields in error. Figure 19 summarizes results of Edit 
processing for fields in error. 


Field Type Fixed Format Variable Format 
Non-Required Field appears in edited result, Field does not 
Field Omitted filled with pad character appear in edited 

associated with Edit Subroutine, result. 
that is, spaces for alphanumeric 

field, zero for numeric field, or 

user -assigned. 


Non-Required Field appears in edited result Field does not 
Field in Error filled with high-values (X'FF’). appear in edited 
result. 


Required Field | Message rejected by EDIT. Message rejected 
in Error or by EDIT. 
Omitted 


Figure 19. Edit Utility Processing of Fields Omitted or in Error 
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6.1 GENERAL CONCEPTS 


The Intercomm File Handler provides centralized control over all 
data file access in the on-line system. Requests for data file access 


are made in message processing subsystems by calling a File Handler 
service routine. 


The correspondence between the normal PL/1 file access functions 
and the Intercomm File Handler service routines is shown in Figure 20. 


Sere == Ss 


Function PL/1 Requests | Service Routine 


= Se a SS SSS a eS Se: Se ee SS 


Prepare a file for access OPEN SELECT 


Access logical records sequentially READ , WRITE GET, PUT 
(QSAM ,QISAM) GET, PUT GET, PUT 


Access logical records randomly READ , WRITE 
(BISAM, BDAM) 


Conclude file access RELEASE 


Figure 20. Functions of File Handler Service Routines 


A data file on-line is identified to the File Handler by the 
existence of a data definition (DD) statement in the execution JCL. 
Files must be existing (DISP=OLD or SHR) except for sequential output 
data sets (DISP=NEW or MOD). 


DD statement requirements are illustrated in Figure 21. 
Additional requirements for VSAM are described in that section. 
Special processing definitions for particular files are defined to 
Intercomm at system startup by FAR (File Attribute Record) parameters. 
These include READONLY (prohibit output), OPEN (at startup), file 
duplexing, etc., and are described in the Operating Reference Manual. 
Additional parameters for file recovery (in case of program or system 
failure) are described in the File Recovery Users Guide. 
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//ddname* DD DSNAME=** 
,DISP=** 
, DCB=(DSORG=** 
, OPTCD=** For BSAM,BDAM,BISAM only. 
, RECFM= Must be specified by existing 
, BLKSIZE= data set label or explicitly 
in DD statement. 


*Name used to identify file in calls to SELECT. 
*kMarks those parameters which must be explicitly specified on the DD 
statement for each data set. 


Figure 21. DD Statement Parameters for the File Handler. 


In centralizing data file accesses, the File Handler provides one 
central set of control blocks for each file, thus reducing core 
requirements in individual message processing subsystems. There are no 
FILE statements in a PL/l-coded Intercomm program. 


Furthermore, all the facilities of the following Operating System 
Data Management functions are accessible to any subsystem: BDAM, BSAM, 
QSAM, BISAM, QISAM and VSAM. 


The File Handler also supports the following ISAM replacement 
access method available from another vendor: IAM. 


Data Base interfaces supported under Intercomm (IDMS, ADABAS, 
TOTAL, DL/I, Model 204, System 2K) are described in the DBMS Users 
Guide and the respective vendors’ manuals. 


6.1.1 Subsystem Processing 


In the on-line environment, several subsystems in concurrent 
execution may require access to the same data file. Rather than each 
subsystem issuing an OPEN and corresponding CLOSE for accessing a 
particular file, the File Handler will open a file the first time it is 
accessed (unless already opened at startup) and the file remains open 
for the duration of the on-line job in execution. A SELECT request 
simply establishes internal control blocks and the corresponding 
RELEASE request merely disconnects those internal control blocks. In 
each subsystem, following a SELECT for a particular file, access 
functions (READ, WRITE, GET, PUT, GETV, PUTV) may be called as many 
times as may be necessary for message processing logic. RELEASE must 
be called for each selected file prior to the return to the System 
Monitor. 
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Each subsystem must provide space for two File Handler control 
areas. The information in these areas is unique for each message 
thread, so they must be defined as automatic variables of reentrant 
programs, so that space can be assigned out of the ISA. To assure that 
they are fullword aligned, they should be defined following a "FIXED 
BIN (31)" field. To force the proper alignment, Figure 22 shows how 
these control areas may be declared for direct calls to File Handler 
routines. 


DCL 1 FH_AREAS ALIGNED, 
3 FH_DUMMY FIXED BIN(31), 
3 EXTDSCT CHAR(48) , 
3 FHCW, 


5 FHCW1 CHAR(1), 
5 FHCW2 CHAR(1), 
5 FHCW3 CHAR(1), 
5 FHCW4 CHAR(1); 


Figure 22. Defining File Handler Control Areas 


If calling File Handler routines via PMIPL1, the FHCW must be declared 
as follows (see also sample program in Appendix D): 


3 FHCW UNALIGNED CHAR(4), 
1 FHCW_REDEF DEFINED FH_AREAS.FHCW, 


5 FHCW1 CHAR(1), 
5 FHCW2 CHAR(1), 
5 FHCW3 CHAR(1), 
5 FHCW4 CHAR(1); 


For each call to a File Handler service routine, the File Handler 
is passed the addresses of the two control areas. The first is an 
aligned 48-character area, called an External DSCT (EXTDSCT), which the 
File Handler uses to save control information for the subsystem 
processing thread, from the time that a given file is first SELECTed 
until it is finally RELEASEd. A unique EXTDSCT must be defined for 
each file concurrently accessed within the same processing thread. The 
other control field, called the File Handler Control Word (FHCW), is an 
aligned four-character field used for communication between the File 
Handler and the calling subsystem. Prior to each call to a service 
routine, the subsystem must clear the FHCW with spaces or initialize it 
with a predefined request code as described for each routine. A code 
of space (blank) is indicated in the detailed access descriptions by 
the lower case letter }#. An example of such a request would be to 
establish Exclusive Control during a call to READ with intent to 
update. The File Handler will return a completion code in this word, 
after servicing a request, to communicate the status of the operation 
back to the subsystem. 
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6.2 CALLING SERVICE ROUTINES 


A PL/1 subsystem may call the File Handler service routines 
through the Intercomm interface module PMIPL1, and provide a 
routine-code name corresponding to the desired routine name, as 
described in the Intercomm ZINCLUDE member PENTRY, or the routines may 
be called directly (see Chapter 3). The PMIPL1 prototype coding format 
is described in Chapter 3. 


The parameters for the File Handler service routines are 
described in Figure 23. The specific parameters passed to a given 
service routine depend on file requirements and the processing options 
of the particular service routine called. If the calling subsystem (or 
subroutine) might be loaded above the 16M line (under XA or ESA), then 
all parameters (except the PENTRY code, if used) must be in Automatic 
storage (DSA), otherwise, the ddname may be in Static storage. 


Parameter Content 

EXTDSCTname A A 48- character fullword- aligned area supplied by the 
subsystem for the File Handler's use for each file 
SELECTed (see Figure 22) 


The File Handler Control Word, in which the File 
Handler returns a completion code to the subsystem 
(see Figure 22) 


An eight-character constant initialized with the name 
of the DD statement describing the data set to 
Intercomm (move from Static to Automatic storage for 
calls from 31-Amode programs) 


The area for data read from, or to be written to, 
the file 


Block-ID Applies only to BDAM files: 


three-byte relative block number (RBN) 
three-byte relative track and record number (TTR) 


eight-byte actual address (MBBCCHHR) 


Figure 23. File Handler Service Routine Parameters 


The File Handler IAM support uses the Intercomm ISAM support routines. 
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On return from a File Handler service routine, the leftmost 
position of the FHCW area will contain a character code indicating the 
result of the operation, as shown in Figure 24, Additionally, for VSAM 
files, the rightmost position of the FHCW will contain a VSAM reason 
code. 


Meaning 


Normal completion 


Invalid request (no DD statement, invalid 
parameter sequence, attempt to output to an input 
only file, etc.) 


Figure 24. Outline of File Handler Return Codes 


The application subsystem logic must then analyze this return 
code and take appropriate error recovery action. An error message 
might be created and queued for output to the terminal. Otherwise, the 
subsystem can return to the Subsystem Controller with a return code of 
12, indicating that the Subsystem Controller should call the USRCANC 
routine which in turn will send an error message to the terminal. 


6.2.1 Automatic Error Checking 


If the application subsystem logic is such that special error 
recovery processing is not required, the File Handler will perform 
error checking itself and data will be returned to the subsystem only 


if the return code is zero. Otherwise, the File Handler will force a 
program check, which causes cancelling of the input message and return 
to the Subsystem Controller, which calls the USRCANC routine. To 


request this function, place a character ‘'C’ in the first byte of the 
FHCW prior to calling a File Handler service routine. 
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6.3 SELECT, RELEASE FUNCTIONS 


SELECT must be called to initialize the subsystem’s EXTDSCT prior 
to any data access function performed by the File Handler. Prior to 
the call to SELECT, the subsystem’s EXTDSCT must be initialized to 
binary zeroes (X‘00'). 


RELEASE must be called to notify the File Handler that its 
pointers to the subsystem’s EXTDSCT should be cleared and that all data 
access to a particular file within one subsystem thread is complete. 
There must be a RELEASE corresponding to each SELECT of a file. 
Multiple SELECTs of the same file using the same EXTDSCT are not 
permitted without intervening RELEASEs, within the same processing 
thread. After each RELEASE, the EXTDSCT should be cleared to binary 
zeroes before being reused. 


Coding format: 
CALL SELECT(EXTDSCTname , FHCWname , ddname); 
CALL RELEASE(EXTDSCTname , FHCWname) ; 


Note: the ddname must be in Automatic storage (DSA) if the subsystem 
(subroutine) can be loaded above the 16M line under XA or ESA. 


Figure 25 describes the return codes for SELECT and RELEASE. 


Return Codes 
(First Byte 
of FHCW) SELECT RELEASE 
A reusable file (disk input) ready Successful 
for access; sequential access begins release 
at first record. 


A nonreusable file (SYSOUT, disk Not applicable 
output (DISP=NEW/MOD or DISP=SHR/OLD 


and FAR WRITEOVER parm specified, or 
a data set on tape) ready for access, 
begins after last record previously 
accessed, 


No ddname found in File Handler File not 
internal control table. (No DD selected. 
statement in JCL or the file has 

been "locked" by the FILE control 

command. ) 


Figure 25. File Handler SELECT/RELEASE Return Codes 
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6.3.1 Closing a File 


Occasionally, it is necessary to close a file, perhaps because it 
is to be updated by a batch job. A special form of RELEASE requests 
the File Handler to close a file. However, unless some external 
control is taken to assure that no other programs have selected the 
file, a close request could cause other transactions for the file to 


fail. Also, if new transactions are attempting to access the closed 
file, the File Handler will open it again and unpredictable results may 
occur. Intercomm provides the FILE system control command for 


systemwide file access control. 
To close a file from an application subsystem: 


e If the file has been previously selected: first release the 
EXTDSCT by calling RELEASE referencing the EXTDSCTname used 
when the file was selected (as described above), then 


e Move a character C to the second byte of the FHCW ('PCH}') 
and call RELEASE supplying the ddname of the file to be 
closed; use the following coding format: 


CALL RELEASE(ddname , FHCWname) ; 


Note: the ddname must be in Automatic storage (DSA) if the subsystem 
(subroutine) can be loaded above the 16M line under XA or ESA. 


6.4 EXCLUSIVE CONTROL FOR NON-VSAM_ FILES 


In a multithread environment with only inquiry applications, the 
fact that several message processing programs may concurrently retrieve 
data from the same file or files presents no operational problems. 
However, when more than one message processing program attempts to 
update or add records to a file, data integrity problems can occur. 
Figure 26 illustrates the problems of concurrent updates; program B's 
update nullifies that of program A. Exclusive control implies that 
while one program is operating on a record, that is, the time between a 
READ and a WRITE, all other requests to read or write that particular 
record will be delayed. A program requesting a record held during 
exclusive control by another program is not notified of this delay, but 
rather stops execution in the File Handler until exclusive control is 
either removed or expires so that the File Handler can then proceed 
with the requested function. Exclusive control, when required, must be 
requested separately with each call to File Handler READ or GET 
functions. Exclusive control for basic access methods operates at the 
block or record level. Exclusive control for queued access methods 
operates at the data set level; thus applications should be designed to 
avoid GET for update whenever feasible. 


To obtain exclusive control over the entire data set in a QISAM 
file or over a physical block in a BDAM or BISAM file, move ‘PXpPp' to 
the File Handler Control Word prior to calling GET or READ. Exclusive 
control does not apply to physical sequential (QSAM/BSAM) files. 
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Exclusive control will be released by: 


e Acall to WRITE or PUT referencing the same EXTDSCTname, that 
is, the update of the previously acquired record, and no key 
or block-id specified. 


e A call to WRITE referencing the same EXTDSCTname and a key 
and/or block-id is specified. 


e A call to READ or GET referencing the same EXTDSCTname 
(retrieving a new record from the file). 


e Acall to RELEASE referencing the same EXTDSCTname. 


e An elapsed time after the call to READ with Exclusive Control 
greater than the exclusive control time-out value of the File 
Handler. This is set at two minutes for any given record and 
a maximum of ten minutes for consecutive exclusive accesses 
to a QISAM file. 


NOTE: A return code of 3 after a call to WRITE or PUT to 
update a record held in exclusive control indicates 
that exclusive control timed out: the WRITE or PUT 
did not take place. The program should re-READ or 
re-GET the same record with exclusive control and 
WRITE or PUT again. 


e Accall to RELEX, if the program logic is such that the record 
does not need to be updated, or additional and time-consuming 
activity (accessing other files) is required before resuming 
access to the file. Such a program could call RELEX to 
release exclusive control without actually RELEASEing the 
file until later in the program logic. 


6.4.1 Release Exclusive Control--RELEX 


RELEX is called to release Intercomm or VSAM exclusive control 
without having to read, update, time-out, or RELEASE the file. 


Coding format: 


CALL RELEX(EXTDSCTname, FHCWname) ; 


Return Code 


Exclusive control released 


File not selected or invalid function 


Figure 27. File Handler Release Exclusive Control (RELEX) 
Return Codes 


59 


Chapter 6 Using the File Handler 


6.5 SEQUENTIAL ACCESS METHOD (SAM) PROCESSING 


6.5.1 File Handler Service Routines--GET, PUT SAM); READ, WRITE 


(BSAM) 
GET is called to access the next sequential logical record from a 
file. PUT is called to write the next sequential logical record to a 
file. READ is called to access the next sequential physical block. 


WRITE is called to write the next sequential physical block. If PUT or 
WRITE is called referencing a disk data set, the record last accessed 
by a GET or READ will be updated, however, the length may not be 
changed. GET processing is subtasked by the File Handler in order to 
provide multithreading facilities; for further details, see the 


Operating Reference Manual. 

Coding format: 
CALL GET(EXTDSCTname , FHCWname , record-area[ ,record-length]); 
CALL READ(EXTDSCTname , FHCWname, record-area[,record-length]) ; 
CALL PUT(EXTDSCTname , FHCWname , record-area[,record-length]); 


CALL WRITE(EXTDSCTname , FHCWname, record-area[,record-length]); 


Return Codes GET, READ 


Successful 


Not selected or invalid Not selected or invalid 

function; that is, using| function; that is, using a 

an output-only file tape input file or readonly 
file, or file not sequential. 


* For WRITE to a disk file: indicates End-of-file (write not done) 


Figure 28. File Handler Sequential Access Method Return Codes 
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6.5.2 Undefined Record Format and Record Length 


The record-length parameter is valid and required only when a 
file with an undefined record format (DCB=RECFM=U) is accessed. The 
record-length parameter points to a fullword containing the length of 
the output record before a PUT or WRITE operation, or to contain the 
length of the input record after a GET or READ operation. The second 
character of the File Handler Control Word must be set to U to utilize 
this feature. Do not code the DCB subparameter LRECL on the DD 
statement for the file in the Intercomm execution JCL. The BLKSIZE, 
RECFM and DSORG subparameters are required. 


6.5.3 Variable-Length Record Format and Record Length 


Variable-length records start with a Record Descriptor Word (RDW) 


which must be fullword aligned. The first two bytes of the word 
contain the record length in binary (+4 for the RDW); the second two 
bytes contain binary zeros (low values). The RDW is followed 


immediately by the record data, and must be recognized by the 
subsystem on input, and provided and initialized on output. 


For blocked files, if GET or PUT are used, the access method will 
perform the blocking and deblocking. If READ or WRITE are used, the 
application program must perform the deblocking (READ) and blocking 
(WRITE). In this case, the block must start with a Block Descriptor 
Word (BDW) of four bytes (aligned); the first two bytes contain, in 
binary, the total block length (including 4 for the BDW), and the 
second two bytes contain binary zeros (low values). For JCL details, 
and FAR options for defining and accessing the file, see the Operating 
Reference Manual. 
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6.6 INDEXED SEQUENTIAL ACCESS METHOD (ISAM) PROCESSING 


To use an ISAM file on-line under Intercomm, do not define three 
DD statements (INDEX/PRIME/OVERFLOW) for either the off-line creation 
of the ISAM data set, or the on-line execution DD statement. For 
creation, let the access method set up the index and overflow areas 
(use CYLOFL parameter on DD statement). For on-line execution, define 
only DISP=OLD and the data set name, volser and unit parameters if not 
catalogued, and the DCB parameter DSORG=IS. Optionally, the DCB 
parameter OPTCD may also be specified. See also the descriptions of 
FAR parameters applicable to ISAM data sets described in the Operating 
Reference Manual. 


6.6.1 File Handler Service Routines--GET, PUT (QISAM): READ, WRITE 
(BISAM) 


GET is called to access the next sequential record, or to 
reposition (if a key is specified) and access the next sequential 
record, READ is called to retrieve a specific record at random. PUT 
is called to update the last record retrieved by a call to GET. WRITE 
is called to update the last record retrieved by a call to READ, or to 
add a record to the file (if a key is specified). For update, 
exclusive control may be requested; otherwise use blanks in the FHCW. 


Coding format: 


to retrieve next sequential record: 


CALL WRITE(CEXTDSCTname, FHCWname, record-area); 
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to add a specific record: 
CALL WRITE(EXTDSCTname , FHCWname, record-area,key) ; 


Figure 29 describes return codes for ISAM access. 


GET w/o Key 


Next sequential 
record retrieved 
1/0 error 

End of File 

N/A 


File not selected 
or invalid function 


WRITE w/o Key 


Record from 
previous READ 
updated 

I/O error 


N/A 


Exclusive Control 
Time-out 


File not selected 
or invalid function 


Figure 29. 


GET w/Key 


Record with equal 
or next higher 
key retrieved 

I/O error 

Key out of range 
N/A 


File not selected 
or invalid function 


WRITE w/Key 
Record with 
specified key 
added 


I/O error 


Key already exists 
or no room to add 
new record 


N/A 


File not selected 
or invalid function 
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PUT 


Record from 
previous GET 
updated 

I/O error 


N/A 


Exclusive Control 
Time-out 


File not selected 
or invalid function 


Record with equal 
key retrieved 


I/O error 


Key does not exist 


N/A 


File not selected 
or invalid function 


File Handler ISAM Return Codes 
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6.7 DIRECT ACCESS METHOD (BDAM) PROCESSING 


BDAM files are accessed by block-id. The form of the block-id is 
defined in the OPTCD subparameter of the DCB parameter of the DD 


statement and the same form must be used by all programs accessing the 
file: 


e OPTCD=RF--block-id is three-byte binary RBN (relative block 
number) for fixed-length files only 


e OPTCD=AF--block-id is eight-byte actual MBBCCHHR 


e OPTCD=F--block-id is three-byte binary TTR (relative track and 
record number) for fixed- or variable-length files. 


The F permits feedback (of block-id) requests: the form of the 
block-id is that requested by the OPTCD parameter. For Keyed BDAM with 
extended search, insert an E immediately after the = sign (that is, 
code OPTCD=<ERF, etc.), and specify the LIMCT subparameter on the DCB 
parameter of the DD statement. 


6.7.1 File Handler Service Routines--READ, WRITE (BDAM) 

READ is called to retrieve a physical block. WRITE is called to 
update a block previously read, to replace an existing block in a 
preformatted file, or to add a new block. 


Coding format: 


CALL READ(EXTDSCTname , FHCWname , record-area[ ,key] ,block-id); 
CALL WRITE(EXTDSCTname , FHCWname ,record-area[ ,key][,block-id]); 
Figure 30 shows FHCW options (byte 2) for standard and keyed BDAM 
files, and when to use key and/or block-id fields. Figure 31 describes 
the corresponding return codes. When reading a keyed BDAM file, the 
key will be read into the key field if a key parameter is passed and 
the key is not used as the search argument (w/o extended search). For 
a keyed BDAM file, replace requires a previous read; update and replace 


are synonymous. 


Intercomm provides two utilities for off-line preformatting of 
fixed-length BDAM files: 


e CREATEGF for BDAM files without keys 
@ KEYCREAT for BDAM files with keys. 


These utilities are described in the Operating Reference Manual. 
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1. BDAM Files Without Keys 


Request 


READ w/o exclusive control, w/block-id 


WRITE to update/replace w/o previous READ, 
w/block-id 


WRITE to add a record--variable-length only WRITE DAF 
(record address returned automatically in 
caller's block-id field) 


2. BDAM Files With Keys 


Request 


A A SS ee ee 


READ data block only w/o exclusive control 
(w/extended search) w/key, w/block-id 
READ data only w/exclusive control 
(w/extended search) w/key, w/block-id 
READ key and data block w/o exclusive control 
w/o extended search, w/block-id (w/key) 
READ key and data w/exclusive control 
w/o extended search, w/block-id (w/key) 


WRITE to update key and data w/o extended 
search, w/key 


WRITE to add a record--next available space WRITE DAF 
w/key, w/block-id (w/extended search) 


*Feedback of record addresses may be requested for these options only 
by placing an F in byte 3 of the FHCW. 


Figure 30. File Handler BDAM Option Codes. 


NOTE: The DI form of the macros (issued in the File Handler) 
requires that the block-id field contains the exact address of 
the data record in the form specified by the OPTCD 
subparameter on the DD statement. With the DK form, if 
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extended search is not specified (via E on the OPTCD subparameter), 
only one track is searched for a record with key matching that passed 
in the key field, and starting at the address specified in the block-id 
field. A WRITE for update of last READ does not need a block-id, as 
positioning is remembered internally. 


1. BDAM Files Without Keys 


WRITE w/o block-id WRITE w/block-id 
Block retrieved Block from previous |Specified block 
READ updated added/replaced 


Block out of range RECFM=F... 
Block out of range 


RECFM=V... 
No space available/ 
block out of range 


File not selected File not selected File not selected 
or invalid function|or invalid function |]or invalid function 


2. BDAM Files With Keys 


WRITE w/o block-id |WRITE w/block-id 


Logical record Record from Specified record 
retrieved previous READ 


Key not found Key not found at 


(READ w/key) block-id saved from 
previous READ 
(WRITE DK only) RECFM=V... 
No space available 


File not selected File not selected File not selected 
or invalid function|or invalid function |or invalid function 


Figure 31. File Handler BDAM Return Codes 
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6.8 VIRTUAL STORAGE ACCESS METHOD (VSAM) PROCESSING 


VSAM support is provided for all three file types: KSDS, ESDS, 


and RRDS. Subsystems designed to access VSAM files use two File 
Handler service routines; GETV and PUTV. SELECT and RELEASE function 
for VSAM as they do for OS data sets. Calls are similar to the 


standard File Handler format, with the File Handler Control Word (FHCW) 
used to specify VSAM options. DD statements for VSAM must specify 
AMP=(AMORG) and for fixed-length data records, ‘RECFM=F’ must also be 
specified on the AMP parameter: AMP=(AMORG, 'RECFM=F’). FAR options 
and execution options for VSAM files such as LSR buffer pool support, 
empty ESDS file load or overwrite, and data set name sharing, are 
described in the Operating Reference Manual. Most users converting 
ISAM to VSAM can continue to use their current File Handler calls. 
Refer to “ISAM/VSAM Compatibility under Intercomm" later in this 
chapter for further details. 


6.8.1 File Handler Service Routines--GETV, PUTV (VSAM) 


A VSAM call may request either sequential or direct access and 
may specify access for KSDS via keys (keyed access) or for ESDS via 
Relative Byte Addresses (addressed access). A keyed access call for 
direct retrieval may provide either a generic key or a full key, and 
may specify a search for either an equal (generic) key or for the first 
greater-or-equal (generic) key. 


A VSAM Relative Record Number Data Set (RRDS) may be accessed 
sequentially, or directly by Relative Record Number. A direct access 
request to a RRDS is made by suppling the Relative Record Number of the 
desired record instead of a key or RBA. All direct accesses to an RRDS 
must specify "full key, search equal." RBA access is not allowed and 
RRNs should not be converted to RBAs for access to an RRDS.- Records 
may be inserted into emply slots in an RRDS but a record may not be 
added with a higher relative record number than the maximum allowed. 
This maximum is specified when the data set is defined to VSAM. 


GETV calls are processed assuming that no update will be 
performed unless the caller so specifies. The caller may switch back 
and forth from direct to sequential access, provided VSAM rules are not 
violated, for example, keyed request against an entry-sequenced data 
set. The File Handler service routine GETV is called for retrieval. 
The File Handler service routine PUTV is called for storage or 
deletion. 


Coding formats: 


For sequential access 


CALL GETV(EXTDSCTname , FHCWname , record- area) ; 
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Coding formats (continued): 
For direct access 


CALL GETV(EXTDSCTname , FHCWname , record-area, (rba)); 
{key) 
{rrn) 


For update of record retrieved by preceding GETV or for sequential 
addition 


CALL PUTV(EXTDSCTname , FHCWname , record-area); 
For direct addition of a new record 


CALL PUTV(EXTDSCTname , FHCWname, record-area, {rba)); 
{key) 
{rrn} 


where: 
EXTDSCTname is the standard File Handler parameter. 


FHCWname is the standard File Handler parameter. Its VSAM use is 
to define processing options and to return completion codes to 
the caller (see Figures 32 and 33). 


record-area is the label of the user’s I/O area. For fixed 
length records, no length is specified and data will start in the 
beginning of the area. For variable length, the first four bytes 
of the area are used as an OS-type, fullword-aligned, variable 
record descriptor word (RDW), the first two bytes of which 
specify the appropriate length in binary (data length +4); data 
begins in the fifth byte. For GETV, the File Handler will return 
this length to the caller and for PUTV, the caller must provide 
the length to the File Handler. 


rba is the label of an aligned fullword containing the Relative 
Byte Address when required for addressed access. 


key is the label of a field providing a key, when required for 
keyed access. If a generic key is provided, then the first two 
bytes of this field must be the length, in binary, of the generic 
key which must begin in byte 3, and the field must be 
fullword-aligned. 


rrn is the address of a fullword-aligned field providing a 


four-byte binary Relative Record Number whose value is 1 to n, 
where n is the maximum record number defined for the data set. 
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6.8.2 VSAM Processing Options 


The following determine the mode of VSAM access to be performed: 


® The preceding call 


A VSAM call is dependent upon the preceding call only in two 
cases: PUTV for update, or sequential GETV or PUTV calls 
requiring initial positioning. 


In the first case, the PUTV call must be immediately preceded 
by a GETV for update, which identifies the record to be 
updated. The PUTV for update has no fourth parameter because 
the key, RRN or RBA was defined by the prior GETV. In the 
second case, a direct call providing a key, RRN or RBA and 
requesting positioning must be issued in order to process 
sequentially starting from that point in the file. To 
request positioning in this manner, specify S in the second 
byte of the FHCW for the direct call to GETV; the first 
record in the sequence will be returned. For an ESDS file, a 
GETV call without a fourth parameter results in sequential 
reads from the beginning of the file; the S in the FHCW is 
unnecessary. 


© The presence or absence of the fourth parameter 


With the exception of a PUTV for update, all calls for direct 
access specify a fourth parameter and all subsequent calls 
for sequential access specify only three parameters. 


® The contents of the File Handler Control Word 


The second and third bytes of the FHCW are used to complete 
the definition of the options desired. Alphabetic codes are 
used and positive tests are made for each defined code. When 
no defined code is present, the default option (blank) is 
used. 


Bytes 1 and 2 of the FHCW are utilized the same as for OS Access 
Methods for Return Codes (Byte 1) and Special Requests (Byte 2). The 
first byte of the FHCW will contain a zoned decimal digit upon return 
from GETV or PUTV. A nonzero value indicates an error or an 
exceptional condition. 


Byte 2 is used in conjunction with direct access. When an § is 
provided in byte 2, the direct access is treated as the first of a 
series of sequential requests which begins at a point specified by the 
fourth parameter. Therefore, a VSAM POINT will be issued and 
sequential access will subsequently be performed for the next call. 
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Byte 3 is used for all VSAM calls as illustrated in Figure 32. , 
There are five default (blank) cases: 


e GETV with three parameters (subsequent sequential access) 
e GETV with four parameters (search key/RRN equal, no update) 


e PUTV with three parameters with no prior GETV for update 
(sequential add/insert) 


e PUTV with three parameters and with a prior GETV for update 


e PUTV with four parameters (direct key/RRN add/insert) 


6.8.3 FHCW Reason Codes for VSAM 


Byte 4 is used to provide VSAM reason codes (from the RPL 
feedback field) upon completion of a VSAM file access request. In 
VSAM, a distinction is made between logical and physical errors. In 
either case VSAM returns a supplementary reason code in hexadecimal 
defining the condition more precisely. Accordingly, the File Handler 
will return this reason code in FHCW byte 4, for the caller's use. If 
the File Handler was called at an ISAM entry point (GET/PUT, 
READ/WRITE), the code returned in FHCW byte 1 may differ from GETV/PUTV 
calls (in order to maintain compatibility with existing ISAM 
subsystems). Figure 33 summarizes VSAM and ISAM/VSAM return codes. 
VSAM reason codes are fully documented in IBM's VSAM: Macro Instruction wi 
Reference or Macro Instructions for VSAM Data Sets. 


6.8.4 Exclusive Control for VSAM Files 


VSAM automatically provides exclusive control of a control 
interval (physical block) whenever a GETV for update is processed if 
the file was defined with SHAREOPTION 1 or 2. The subsystem must 
release this exclusive control via a call to RELEX before another GETV 
is issued for the same file, unless an intervening PUTV for update or 


erase is issued. If no subsequent GETV will be issued, the call to 
RELEASE will also release exclusive control. There is no VSAM 
exclusive control time-out. If the VSAM file is accessed by more than 


one region (Intercomm and/or batch), see IBM documentation on VSAM 
SHAREOPTIONs, and the Intercomm Operating Reference Manual. 
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( 6.8.5 Alternate Path Processing of Keyed VSAM Files 


Base Cluster and Alternate Path processing of keyed VSAM files is 
supported with the following (VSAM-imposed) restrictions: 


e If defined in the JCL, the DD statement for the base cluster 
must be before those for any related paths, and open at 
startup must be requested via a FAR. Also, both the base 
cluster and the paths must be connected to an LSR buffer 
pool. 


e Each path to be accessed on-line must be defined in the JCL 
and be SELECTed with the corresponding ddname. When created, 
the path must be defined with the UPDATE option. 


e The FAR READONLY option must be specified for all paths and 
the base cluster (if defined) except for the path used for 
updating, when Shareoption 2 is in effect for the base 
cluster. If updating is only via the base cluster, then 
READONLY must be specified for all associated paths. VSAM 
will not allow any accesses to a base cluster under 
Shareoption 1 when one path has opened it for update. A base 
cluster under Shareoption 3 may be accessed for reads or 
updates by more than one path at any time, however no 
exclusive control (read/write file integrity) is provided by 
either VSAM or Intercomm. For Intercomm-provided exclusive 
control for Shareoption 4, see the Operating Reference 
Manual. 


e If multiple paths are accessed, and/or retrieval/update is 
done via the path(s) and the base cluster, retrieval of 
updated versions of the records can be ensured via the FAR 
DSN and LSR parameters. 


e Since duplicate keys may occur in an Alternate Index, the 
application program is responsible for checking for duplicate 
keys. Sequential processing (GETV type 1) can be used after 
the first GETV with key (and an S in byte 2 of the FHCW) in 
order to retrieve subsequent records. The program can test 
to see if the last record under a duplicate key was retrieved 
by checking the VSAM reason code which will be placed in byte 
4 of the FHCW. See IBM's VSAM Macros manuals for reason code 
values. 


e@ The alternate index data set must be defined with the UPGRADE 
attribute and be built prior to Intercomm startup. An 
attempt to retrieve a record from an empty file will cause a 
program check. 


e Alternate index data sets should not be defined in the JCL 
unless access to a data record containing the prime keys is 
desired, or path processing is not used. Only readonly 
processing should be done for an AIX and for any related 

: paths and for the base cluster, otherwise, retrieval of the 
CC current version of a record is unpredictable. 


71 


Chapter 6 


ae 
1 


Access or 


Service 
Routine Action 


Sequential 


Sequential 
Direct 
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Direct 
Sequential 


Add or 
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Direct 
Add or 
Insert 


Add 


Figure 32. 
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Key 


Generic 


Generic 
Key 


sequence 


In RBA sequence 
(default for 
ESDS) 


Search greater 
or = (not valid 
for RRDS) 


Search = 
(not valid for 


Search greater 
or = (not valid 
for RRDS) 


Addressed Access 


No prior GETV for 
update (insert 
not allowed for 
Addressed Access) 


Prior GETV for 
update required 
(Addressed Access 
update may not 
change length) 


Prior GETV for 
update required 


(not valid for 
Addressed Access) 


(no prior GETV) 


Insert not valid 


File Handler VSAM Call Summary 
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Byte 4 
(hexadecimal) 


ondition at Completion of Operation* 


Successful completion (A) 


End of data (1, 2) 04 

No record found (3, 4,5, 6,7) | 2] 2 | ~ 1000 

Key not within defined key ranges | 2 | 1 | | mo 
(3, 4, 5, 6, 7) 

Duplicate key (8,11) | 9 | 2 | 26 

Key out of ascending sequence (8) | 9 | 2 | oc) 

Update attempt with new key (9) | 9 | 9 | | 6 

Key exceeds maximum (5,6) | 9 | ef 7 

Addressed update changes length (9) | 9 | ** | rn 

Invalid RBA provided (7,12) | 9 | | 2002¢~C~* 

Required positioning not performed | 9 | ** | ee 
(1, 2, 8) 

Direct or update call while loading (8)} 9 | 9 | mo 

GETV for ESDS while loading (2,7) 

Insufficient disk space (8, 9, 11,12) | 9 | 9 | | I 

Record on unmountable volume | 9 | 9 | Bo 
(1-7, 11, 12) 

Invalid Relative Record Number (3,11) | 9 | ** | co” 

Invalid RBA access to a RRDS file (7,12) 9 | ** | ho 


*Characters in parentheses reference the type(s) of VSAM Call 
(Figure 32) which apply. A = all cases. 


**Should not occur. The File Handler will force a program check 
condition to terminate the message in progress. 


Figure 33. File Handler VSAM Return and Feedback Codes 
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6.9 ISAM/VSAM COMPATIBILITY UNDER INTERCOMM 


Subsystems accessing ISAM files can function with little or no 
modification when their files are converted to VSAM. Intercomm’s 
ISAM/VSAM interface does not use IBM’s VSAM/ISAM interface modules. 
See the Operating Reference Manual for steps necessary to activate the 
interface. When processing a VSAM data set, the File Handler uses 
QISAM compatible access for a GET or PUT call and BISAM compatible 
access for a READ or WRITE call. 


An ISAM retrieval is converted to a VSAM GET for update. If a 
key is provided, it is, of course, treated as a full key. For GET with 
a key, positioning and a search for a greater or equal key is 
performed, For READ, a search is made for an equal key. File Handler 
logic will initialize the user FHCW prior to performing the VSAM 
function as follows: 


e Byte 2 is set to ‘S' to force sequential positioning. 
e Byte 3 is set to 'U’ or ‘'L’ to force update mode. 


ISAM delete code processing continues to function as usual via 
the OPTCD subparameter of AMP on the DD statement. The new OPTCD 
parameters (I, IL) which specify supplementary delete code processing 
are supported also. 


The following considerations apply to ISAM users converting to 
VSAM and should be carefully observed: 


e ISAM subsystems must already be operational for ISAM files 
before accessing VSAM files. Erroneous ISAM parameter lists 
will cause unpredictable results. 


e Between a SELECT and a RELEASE, neither READ and GET nor 
WRITE and PUT may be intermixed. 


e The caller may not provide his own DCB. 


e The FHCW will be modified in order to convert the call to its 
VSAM equivalent. 


e There is no equivalent to a QISAM physical block once the 
file has been converted to VSAM. All VSAM data records are 
equivalent to ISAM logical records. This means that users 
processing the file via READ in one subsubsystem and GET in 
another will both retrieve what would have been an ISAM 
logical record. 


Figure 33 describes return codes when ISAM/VSAM compatibility is 
used. 
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USING THE OUTPUT UTILITY 


7.1 CONCEPTS 


The Output Utility is a subsystem that processes messages 
destined for terminals operating under control of Intercomn. It is 
responsible for completing any device-dependent formatting requirements 
in a message before passing it to the teleprocessing interface (FESEND) 
for eventual transmission to the terminal device. It also checks the 
operational status of destination terminals. Should it find a 
destination terminal not operational, it will redirect messages to an 
alternate terminal, if one has been named for that particular 


destination terminal. Otherwise, the Front End will intercept a 
mesSage to a nonoperational terminal and queue it in the output queue 
assigned to that terminal to await its availability. If an alternate 


terminal name has been provided to the Front End Network Table, and the 
alternate can receive output, then the Front End will dequeue the 
message queued for the nonoperational primary terminal and send it to 
the alternate as soon as possible (useful primarily for non-functional 
printers). 


7.2 PROCESSING 


An application subsystem may create four different types of 
output message text, identified by a value in the message header VMI 
field (MSGHVMI): 


e Preformatted (VMI=X'57' or C'P') 


Text consists of both data and device control characters. 
All spacing and other formatting (titles, column headings, 
etc.) is included in the message text. Output processing 
consists merely of passing the message to the Front End via 
FESEND. If the destination terminal (MSGHTID) is the name of 
a broadcast group, rather than an individual terminal, a 
separate message is created for each terminal of the group. 
Except for broadcast terminal-ids, subsystems should use the 
service routine FESEND, which is more efficient than queuing 
via Output. 
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e Formatting Required, Variable Text (VMI=X'50' or C’0’) 


Text consists of a string of character data items to be 
inserted into a final message format defined by an Output 
Format Table (OFT) entry. Each data field is prefixed with 
an item code and length prefix, and an occurence factor (if a 
repetitive field), to identify the field. The OFT defines 
the position and content of titles, headings, etc., and 
defines the position where data fields from the message text 
are to be inserted. Output formats the final message, adding 
device-dependent control characters, and performs broadcast 
group processing, as described above. 


e Formatting Required, Multiple Segments (VMI=n) 


This form is used when multiple messages are to be created 
for the same hardcopy terminal (such as a printer) and inter- 
leaving of other messages for the same device is not 


desired. The text is variable format as described above. 
The VMI code for the first (or header) segment is X'51' or 
C'l’'; for intermediate segments is X'52’ or C'2' or X‘5C' or 
C'4' depending on line types desired; and for the final 
seqment is X'53' or C'3'. The final segment must be queued, 


even if no intermediate segments are created, in order that 
Output may release the terminal for other messages. 


e Formatting Required, Fixed Text (VMI=X'72’ or C'S’) 


Text consists of fixed length text fields in character or 
arithmetic format. This type of message is routed to the 
Change/Display Utility, where it is converted to a Variable 
Text message and routed to the Output Utility. The fixed 
text is described to Change/Display by a Format Description 
Record (FDR). The first twelve bytes of the fixed format 
text identify the particular FDR which details the fixed 
fields of the message. Byte 9 within this header provides 
the segment type (see Figure 34). 


The application subsystem creates its output message (header and 
text) and directs the message to either the Output Utility or the 
Change/Display Utility by calling the service routine COBPUT. The 
receiving subsystem codes and VMI in the message header specify the 
destination subsystem and message text formatting requirements. Figure 
34 summarizes message header specifications. In addition, the MSGHQPR 
field in the message header must be set to C'2’' if the originating 
subsystem might process segmented input. 


The sample subsystem in Chapter 12 provides examples of using the 
Output and Change/Display Utilities. For complete details regarding 
the Output Utility and Change/Display Utility, refer to the Utilities 
Users Guide. 


76 


Chapter 7 Using the Output Utility 


Message Header Fields Change/ 
Display 
OUTPUT Message Type MSGHRSCH | MSGHRSC | MSGHVMI]| Prefix 


Preformatted (device-dependent) 


Variable Text Formatting: 


Single Segment Messages: 
character format for item 


code, length 
(and occurrence number) 


binary format for item code, 
length (and occurrence number) 


Multi-Segment Messages: 
character format 


first segment 


detail segment 
- repetitive data items 


detail segment 
- non-repetitive data items 


final segment 


binary format 
first sepment 


detail segment 
- repetitive items 
detail segment 
-non-repetitive items 


Fixed Field Formatting: 


Single-Segment Messages: 


detail segment 

- repetitive items 
detail segment 

- non-repetitive items 
final segment 


NOTE: COBPUT converts character codes to the corresponding 
hexadecimal values for VMI codes, and MSGHRSCH to X'00'. 


Figure 34. Message Header Specifications for the Output Utility 
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CONVERSATIONAL SUBSYSTEMS 


8.1 GENERAL CONCEPTS 


Conversational subsystems are defined as one or more subsystems 
designed to process more than one input message to complete a 
transaction. They effectively carry on a dialogue with the terminal 
operator, receiving an input message, retaining it and/or associated 
results of processing, issuing a response (perhaps a prompt for 
additional information), receiving another input message, retaining it, 
etc., until the transaction is complete. At the end of the 
conversation, appropriate files may be updated. 


8.1.1 Conversational Applications 


Typical applications which lend themselves to conversational 
processing are: 


e Operator prompting (multiscreen input) 
e Batch Data collection 


Prompting, or multiscreen input, applications typically consist 
of dialogues in which the terminal operator enters an input message, 
the information is analyzed by the application subsystem and the 
results of processing are saved; the application subsystem then sends 
an output message to the terminal, prompting the operator for the next 
piece of information required. This dialogue continues until the 
application subsystem has obtained all the necessary information to 
complete processing for the given transaction. 


Batch data collection may be conversational in that even though 
the input data is saved for later retrieval, the collecting application 
may need to return an error message requesting correction of invalid 
input data before saving the input record, or the application may need 
to request the input of a different type of record (for more detailed 
subsidiary information, intermediate totals, etc.). 


8.1.2 Conversational Transactions 


Conversational transactions involve the sending and receiving of 
more than one message in a terminal session. Each input message may be 
processed by related subsystems or by the same subsystem. A two-part 
conversational transaction is illustrated in Figure 35. 
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customer name MESSAGE 
status request 


4 account number RESPONSE 


current status 


sales order data MESSAGE 


<4 verification of order RESPONSE 


Figure 35. Typical Conversational Transactions 


8.1.3 Retention of Information 


Assume a conversation in which three input messages and three 
responses are necessary to complete the transaction. A terminal, a 
subsystem and a storage medium on which to save the input messages, 
and/or corresponding intermediate results of the processing, are 
necessary components in the conversational environment. In the example 
illustrated in Figure 36, the subsystem receives information and 
prompts the terminal operator for additional information until it 
obtains all the required data. This intermediate information is also 
stored either in core or on a disk data set. After the final input 
message is received and processed, appropriate files are updated, 
intermediate data is deleted, and a final response is issued. 


== SS SO SS Ss oe ee See wee eee ee: 


Terminal XYZ Subsystem ABC Storage 


A AS NS SS SS SS SEK ES ee ce ee ee ee ee ee 


Input Message 1---> Receive, process and store----> Input Message 1 
+ results 


Output Message 1<---Prompt for additional information 


Input Message 2---> Receive, access Input Message l<--Input Message 1 
Process + results 

Also store Input Message 2 Input Message 2 
+ results 


Output Message 2<---Prompt for additional information 


Input Message 3---> Receive, analyze with prior <---- Input Message 
messages and results 1 & 2 + results 
Update files, delete prior data 


Output Message 3<---Final response 


Figure 36. Input Message Data Retention During a Conversation 
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8.2 IMPLEMENTING CONVERSATIONAL SUBSYSTEMS 


Conversational subsystems may be implemented in several ways, 
each characterized by the retention of initial and subsequent input 
and processing results. The method of retention differs, depending 
upon the method of implementation chosen. 


Control of the conversation, or the retention of the input 
messages and/or corresponding results of processing may be 
accomplished by using any one of the following methods of 
implementation: 


e The User SPA (User Extension to System Parameter List) 

e The Store/Fetch Facility 

e The Dynamic Data Queuing Facility 

e The CONVERSE Service Routine 

In addition to the retention of the input environment, 
conversational subsystems have design considerations with respect to 
file updates and control of input verbs. These design considerations 
are discussed following a review of the four methods of retention of 
input messages and corresponding results of processing. 

Intercomm provides Front End conversational support to ensure 
that duplicate input is not processed. This is accomplished by 


defining applicable verbs and interactive terminals as conversational 
in the Front End tables. See the Operating Reference Manual. 
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8.3 SAVING INFORMATION IN USERSPA 


The user extension to the SPA is called USERSPA and is accessible 
to all Intercomm subsystems since the SPA is the second entry parameter 
to all subsystems. The SPA (Csect) is a 500-byte core-resident table. 
The user extention to the SPA begins at the 50lst byte and may include 
application-oriented areas, such as tables, counters, and switches for 
application subsystem use. Thus, the size of USERSPA is installation- 
dependent. The user portion of the SPA is optionally checkpointable 
and can be restored at system restart time. 


A portion of USERSPA may be divided into sections associating 
table space for each terminal, as illustrated by Figure 37. Each 


terminal-oriented area might be used for control data during 
conversational processing, until the conversation with that terminal 


completes. 
cl 
ae | 


User B Area 


COPYed 
member 
TERMINAL/ Table for TID1 
TABLE 
SPACE 
Table for TID2 USERSPA 


Figure 37. User and Terminal Table Space in the USERSPA 


The SPA is expanded by updating the Assembler Language member 
USERSPA on the system release library SYMREL. The updated version 
should be stored on SYMUSR. When assembling INTSPA, USERSPA is copied 
as the last entry in the SPA Csect. Therefore, any user additions would 
be referenced beginning with the 50lst byte. Any such additions should 
ordinarily be cocrdinated through the System Manager, as most 
application subsystems could be affected. 
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In the based structure definition of SPA, as shown in Figure 38, 
three different applications have their own 50-byte areas defined: 
(USERA_AREA, USERB AREA, USERC_AREA) plus a table for their common use 
(COMMON_TABLE). The Assembler Language member USERSPA for this example 
would contain a definition of an area corresponding to OURSPA. OURSPA 
could be defined as a systemwide member to be included by all PL/1 
routines using a ‘ZINCLUDE OURSPA;’ statement following the INTSPA 
statement. 


DCL 1 FULLSPA —_ BASED(SPA), 
5 INTSPA CHAR(500), 
5 OURSPA, 
6 COMMON_TABLE CHAR (200), 
6 USERA_AREA CHAR(50), 


6 USERB_AREA, 
8 COUNT_FIELD1 FIXED BIN(31), 
8 ON_OFF_SWITCH  CHAR(1), 
8 REST-OF-AREA CHAR(45), 
USERC_AREA CHAR(50); 


Figure 38. Sample USERSPA Declaration Within a Subsystem 


The following chart summarizes the advantages and disadvantages 
of the USERSPA method of implementation of conversational processing. 


Advantages Information saved in Core; no I/0 overhead. 
Accessed easily. 
Checkpointable and restorable at restart. 
Disadvantages The entire USERSPA is accessible to all Intercomm 
subsystems. Therefore a problem of control develops 
with respect to the possiblity of destruction of data 


by another subsystem, or security problems. 


Updating and maintenance of USERSPA may require 
recompiling all subsytems which reference it. 


A potentially large area of storage must be allocated. 


Addressability, if area larger than 3596 bytes. 
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8.4 SAVING INFORMATION WITH STORE/FETCH 


Conversational information may be stored and later retrieved 
(either in storage or on a disk data set) by the Store/Fetch Facility. 
Information is retained via the STORE function, and retrieved via the 
FETCH function. The storage space may be released via the UNSTORE 
function. Saved information may also be updated. 


An operator prompting type of conversation involving one terminal 
and one or more application subsystem(s) could use Store/Fetch very 
efficiently for retaining information. Store/Fetch performs its 
function upon data strings. Data strings are logical entities of 
information (input messages to be retained or whatever other data the 
user intends to save), which are identified by unique user-defined 
keys. The information is accessible only to those subsystems which 
call a Store/Fetch service routine naming the data string by its unique 
key, which could include the current terminal-ID from the input message 


header. Therefore, there is more control over the information than 
there would be if it were to be saved in the USERSPA. The data strings 
are classified as either transient, semipermanent or permanent. The 


differences between these classifications are as follows: 


= ee =< Se SSS SS SSS SS SS SS SS SES = ae = — se: 


Disposition Availability Storage Medium 


Transient Not available across restart Core or disk 


Semipermanent Available across restart Disk 


Permanent Available across every system Disk 
start until explicitly unstored 


In conversational processing, permanent data strings should not 


be used. As to whether to use transient or semipermanent strings, the 
user must decide whether the information is critical enough to be 
preserved across system restart. If so, the data strings would be 


classified as semipermanent and would reside on disk. At restart time, 
the operator could then resume a conversation at the point of failure 
if subsystem logic can determine when the conversation was 
interrupted. If stored data is specified as transient, data is 
eligible to reside in core. Processing would thus be speeded up, as 
I/O overhead would be eliminated. At restart time, the operator would 
then start the conversation from the beginning. 


Detailed information on Store/Fetch, including the interface 
between application subsystems and the Store/Fetch service routines, 
may be found in Store/Fetch Facility. Application subsystem logic must 
determine whether the input message in progress is initial, 
intermediate or final. This determination is necessary to assure that 
the proper calls to Store/Fetch are issued when data is to be saved or 
retrieved. Once the determination is made, Store/Fetch may be used to 
manage the conversational information as shown in Figure 39. 
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Initial Input: 


STORE--create a new data string 


Intermediate Input: 


FETCH--retrieve existing data string 


STORE--update string: new information merged with existing data 


Final Input: 


FETCH--retrieve existing data string 
Process input and merge final information with existing data 
Update necessary files and create final output message 


UNSTORE--free data string storage 


Figure 39. Conversational Processing Using Store/Fetch 


Subsystem processing logic can be simplified by using one or more 
of the following techniques: 


e@ A ‘string-not-found’ return code from a FETCH request 
indicates intial input (no intermediate data stored). 


e A FETCH with the Delete option forces restart of the 
conversation from the beginning if the system fails, or the 
subsystem times out or program checks before the STORE of the 
intermediate data can be done. This technique also saves 
Store/Fetch and core storage resource overhead. 


e The STORE of the intermediate data should be done after the 
output message is processed. 


e File record(s) should not be updated until all intermediate 
data is collected. At this time the record(s) should be 
retrieved for update (exclusive control) and checked for 
external updates by unrelated processing since the 
conversation began. 


e@ Do not send the final confirmation output message until 
successfully updating the file(s). 
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8.5 SAVING INFORMATION ON A DYNAMIC DATA QUEUE 


The Dynamic Data Queuing Facility (DDQ) is a Special Feature 
available to Intercomm users. Detailed specifications on using DDQ may 
be found in Dynamic Data Queuing Facility. A DDQ provides the 
application subsystem with the ability to dynamically create, retrieve 
and delete logical data sets (or queues) of records on a BDAM data 
set. As illustrated in Figure 40, more calls are required to interface 
with the DDQ routines than are required to interface with Store/Fetch 
to obtain the same functions. However, a DDQ provides the ability to 
save several related data strings as a type of sequential file. The 
entire DDQ can then be processed by another subsystem or postponed for 
batch processing. A DDQ is most effectively used, not as a means for 
temporary storage of data during a conversation, but as a means for 
accumulating conversational results for subsequent processing, that is, 
for data collection. This facility can also be used for collecting 
data from related conversations with more than one terminal. 


The data queues may be either transient, single-retrieval 


transient, semipermanent or permanent. Single-retrieval transient 
queues cannot be read more than once. This type of DDQ, therefore, 
would not be suitable for conversational processing. The other queue 


types are distinguished by the following characteristics: 


Queue Type Characteristics 
Transient Must be passed to another subsystem or 
Cannot be retrieved later. 


Not preserved across restart or normal 


Semipermanent | Retrieved at a later point in time via 
user-provided Queue Identifier (QID). 


Extra I/O overhead is involved in saving the queue. 


Can be freed by user request. 


Queue must be completed (closed) in order to be 
preserved across restart. 


Existing semipermanent queues freed at normal startup. 


Permanent Same characteristics as semipermanent except that 
permanent queues are always preserved across any 
Intercomm start, warm or cold, if closed at least 
once. 
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Figure 40 illustrates typical use of DDQ facilities in 
conversational processing. The application subsystem logic must 
determine whether input is initial, intermediate, or final. Final 
input, in this example, causes the queue to be closed and passed to 
another subsystem for asynchronous or postponed file updating. Thus, 
the terminal operator, upon receipt of the final output message, can 
begin another conversation without waiting for file updates to occur. 
This technique is particularly useful for files which do not require 
up-to-date inquiry response such as order entry, personnel, etc. 


Initial Input: 
QBUILD -- Create a new queue 
QWRITE -- Save input message and related data 
QCLOSE -- Save the DDQ 
Intermediate Input: 
QOPEN -- Open the queue 


QREADX -- Read the record or QWRITE to add 
with intent to update to the queue 


QWRITEX -- Update the record 
Save the DDQ 
Final Input: 
QOPEN -- Open the queue 
QREADX -- Retrieve the record or QWRITE to add 
to the queue 


QWRITEX -- Update the record 


QCLOSE -- Pass the DDQ to another subsystem which will update 
files and free the queue. 


Issue final output message. 


Figure 40. Conversational Processing Using Dynamic Data Queuing 
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8.6 SAVING INFORMATION VIA THE CONVERSE SERVICE ROUTINE 


The final method of retaining information for a conversation is 
to use the Intercomm system service routine CONVERSE. The CONVERSE 
routine is called by an application subsystem when input from the same 


terminal is required to continue processing a transaction. The 
application subsystem stops processing until the next input message is 
received from that terminal. Control is returned to the next 


sequential instruction following the call to CONVERSE. 


Application subsystems are designed more easily with CONVERSE, as 
it is simpler to control the sequential order of the messages. 
However, the use of CONVERSE is not encouraged, as it ties up Intercomm 
resources. Dynamic storage (ISA area) associated with the initial and 
subsequent input messages is retained during the call to CONVERSE. 
Storage requirements for subsystems would be greater than when other 
conversational techniques are used, because one subsystem contains 
logic for all message types of a conversational transaction. It is far 
more efficient to design conversational subsystems which retain control 
only for the amount of time necessary to process one message than to 
tie up system resources while each input message in the conversation is 
in turn received, kept, analyzed and responded to in one execution of 
one application subsystem. When CONVERSE is used, dynamically loaded 
subsystems remain in storage until all "conversations in progress" have 


terminated. Intercomm restart processing of such subsystems restarts 
the conversation from the beginning. All intermediate messages are 
discarded. 


The saving of information in the USERSPA or in a Store/Fetch data 
set or in a DDQ does not require an application subsystem to contain 
logic for time-outs. The use of CONVERSE does. If the next input 
message is not received in the time limit specified by the user, a 
time-out occurs, which must be handled by subsystem logic. 


An example of the use of CONVERSE in a two-part conversation is 
illustrated in Figure 41. 


NOTE: CONVERSE is not supported for subsystems loaded above the 16M 
line under XA or ESA. 
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SUBSYSTEM 
CALLED BY 
MONITOR 


PROCESS 
INPUT 
MESSAGE A 


Part A Logic 


FORMAT 
OUTPUT 
MESSAGE A 


[| CONVERSE | 
SAVE THE 
INTERCOMM 

ENVIRONMENT 


Part B Logic PROCESS 
REPLY 


MESSAGE B 


FORMAT 
OUTPUT 
MESSAGE B 


RETURN TO 
MONITOR 


Figure 41. 


Conversational 


Conversational Subsystems 


Beginning of Conversation 


Pass Message to Front End 


CONVERSE saves terminal 
identification, subsystem code, 
storage pointers, etc. 


When the next message with the 
same terminal-id arrives, the 
subsystem resumes from this point 
referencing the original areas 
and the new message. 


Pass message to Front End 


Subsystem Logic Using Converse 
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8.6.1 Subsystem Design Using CONVERSE 


The Intercomm system service routine CONVERSE is called when 
awaiting additional input in response to some prompting message. Since 
any interval may elapse before the next message is received, CONVERSE 
will save information in its own control table for each conversation 
and return to the Subsystem Controller while waiting for the response. 


The call to CONVERSE specifies a time limit within which a reply 
message should be received. If it is not received during the specified 
interval, then the subsystem is entered at the next instruction 
following the call to CONVERSE and its message parameter is adjusted to 
point to a time-out message supplied by CONVERSE. That message (header 
plus text) could then be switched to the Output Utility or FESEND. The 
terminal identification in the header is that of the non-responding 
terminal. A zero value for the time limit will bypass the automatic 
time-out feature. 


Coding format: 


CALL CONVERSE(word,time) ; 


where: 
word 
is the name of an aligned fullword (FIXED BIN(31)) in the 
subsystem’s DSA required by CONVERSE for work space. The 
fullword must be CHAR(4) if CONVERSE is called via PMIPLI1. 
time 


is the name of an aligned fullword binary value (FIXED 
BIN(31)) indicating a limit (in seconds) within which a 
subsequent message is anticipated. 


When processing resumes following the call to CONVERSE, the 
environment appears as it was before the call--except the input message 
parameter (unless there was a time-out) now points to the most recent 
message from the terminal. It will have been edited if specified for 
the verb’s definition in the Front End Verb Table. The Intercomm 
return code area will contain a binary value in the low-order byte 
indicating the condition for return from CONVERSE (see Figure 42). 


The CONVERSE program keeps track of conversational requests by 
terminal and subsystem, and separates messages accordingly. Hence, any 
subsystem may be in conversation with any number of terminals 
simultaneously. 


It is the subsystem’s responsibility to verify that the message 
received following the call to CONVERSE is actually the appropriate 
message expected in the logical sequence of the conversation. 


To use CONVERSE by a PL/1 subsystem, PLILNK=NONBASED is required 
on the SYCTTBL macro definition (see Chapter 3), the input message 
parameter must be declared as a pointer, and the input message area 
must be BASED on that pointer. 
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Note that the CONVERSE routine may only be called from a 24-Amode 
subsystem. Due to complications arising in reestablishing internal 
pointers on return from the call to CONVERSE, it may not be called by a 
PL/1 or COBOL subroutine of the subsystem. 


For example: 


e Monitor calls PL/1 Subsystem AA which calls CONVERSE (valid 
sequence of program logic). 


e Monitor calls PL/1 Subsystem BB which calls Assembler 
Language subroutine Bl which calls CONVERSE (valid sequence 
of program logic). However, if the new input message 
processed by the Assembler Language subroutine on return from 
the call to CONVERSE is freed by the subroutine or passed by 
it to another subsystem or FESEND, then the subroutine must 
zero the first word in the parameter list passed to it (see 
Assembler Language Programmer's Guide). The calling PL/1 
subsystem may then not reference the input message area or 
any of its data fields (except for data fields in its DSA 
passed aS parameters to the BAL subroutine for storing 
message data and/or a copy of the new message header for the 
next output message). Note that the BAL subroutine may use 
the new return code address parameter to pass a code back to 
the PL/1 subsystem, or the PL/1 subsystem may test it for the 
CONVERSE return code on return from the BAL subroutine. 


e Monitor calls PL/1 Subsystem CC which calls PL/1 subroutine 
Cl which calls CONVERSE (invalid sequence of program logic). 


The PL/1 subsystem may not use an old copy of the message header for a 
new output message. 


Conversational subsystem logic must be designed with care 


regarding file access. Selected files should be released prior to the 
call to CONVERSE. If not, other subsystems accessing the same files or 
other messages in process in the same subsystem may "time out." This 


may occur because an operating system control block is associated with 
the access to the file and is not "freed" until the file is released. 
If a file is accessed prior to the call to CONVERSE and released after 
the call to CONVERSE a "lock out" situation may occur. 
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RS 2 


Return Codes Meaning 


(X'00') Normal return: the entry parameter input-message 


reflects the address of the new input message. The 
message will have been edited successfully if the 
Front End Verb Table shows editing required. (If 
editing is unsuccessful, error messages will be sent 
to the terminal, and the subsystem is not reactivated 
until either a subsequent input message is edited 
successfully or an automatic time-out occurs.) 


CAUTION: The CONVERSE automatic time-out is not 
extended if a message is found in error by 
the Edit Utility. 


No core available for CONVERSE control blocks; 
conversational mode not initiated. 


18 (X'12') Time-out expired. The entry parameter input-message 
reflects the address of an error message generated by 
CONVERSE. The message header contains the appropriate 
terminal identification. The message text is: 


*PMI*XCONVERSE*ANTICIPATED MESSAGE NOT RECEIVED 
WITHIN USER SPECIFIED TIME INTERVAL 


Figure 42. CONVERSE Return Codes 


Control of the conversational program environment is accomplished 
by Intercomm in different ways, depending on the subsystem’s residency: 


Resident 


The dynamic storage area (ISA) for one message from a 
terminal is retained pending arrival of the next message from 
that terminal; the subsystem will continue to process 
messages from other terminals. 


Overlay Loaded 
Same as above, except the loaded overlay region may contain 


other subsystems to process other messages during (and after) 
"CONVERSE time." 


Dynamically Loaded 


Same as above, except the subsystem remains in core until all 
"conversations in progress” have terminated. 


92 


Chapter 8 Conversational Subsystems 


8.7 DESIGN CONSIDERATIONS IN CONVERSATIONAL PROCESSING 


In order to ensure file integrity, conversational subsystems 
performing file and/or data base updates should be designed to perform 
the updates for the last message in the conversation. Alternatively, 
control may be passed (via message queuing) to a non-conversational 
subsystem to perform the updates. 


8.7.1 Control of the Input to Conversations 


Conversational subsystems expect ordered input. They must be 
designed to analyze input messages and to determine which message in 
the sequence has been received. Control of the input may be exercised 


by the terminal operator or by the application subsystem(s). 


The terminal operator may be given a specific sequential list of 
Messages to input at the terminal for a given verb or verbs. This 
method would probably be used for data collection applications, in 
which more messages are sent to the application subsystem than are 
received at the terminal. It could also be used for any conversational 
application in which the order of input is fixed. 


The application subsystem may control the input sequence by 
analyzing an input message, processing it, and issuing a response 
informing the operator about the content or format of the next input 
message. The response may direct the operator to input another verb 
(that of a related subsystem). Subsystem-controlled input is good for 
conversations in which the "next" desired piece of information may vary 
depending upon the contents of a file record, or a table, or the 
setting of a switch in the area saved between subsystem activations. 


8.7.2 Assigning a Verb to a Terminal 


To eliminate the requirement for an operator to key in a verb 
with each input message, the operator may enter a system control 
command message to LOCK a specific terminal to a particular verb. The 
Front End then prefixes that verb to each input message from that 
terminal. The operator may enter another control message, UNLK, to 
unlock the terminal from the verb. See System Control Commands. 


The LOCK/UNLK commands processed by the Front End can also be 


issued by a _ subsystem. When a LOCK is in effect, all subsequent 
messages from the specified terminal will be automatically prefixed by 
the verb specified in the LOCK command. This LOCK remains in effect 


until UNLK is issued. With LOCK in effect, some advantages are: 


e The terminal operator does not have to keep reentering the 
same verb. 


e A new verb cannot be entered during the conversation. 
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Either the subsystem or the operator may control the input 
sequence by locking and unlocking the terminal to different verbs at 
different points in, or at the end of, the conversation. 


Optionally, the Intercomm AUTOLOK feature may be defined for the 
verb in the Front End Verb Table, which dictates that when that verb is 
input from the terminal, the terminal is to be automatically locked to 
that verb. Subsequently, the terminal is to remain locked until 
specifically UNLKed by the operator or processing subsysten. 


The format for the LOCK/UNLK commands (message text) is as 
follows: 


LOCKS TPUxxxxx$ vvvv@ 
UNLKSTPUxxxxx@ 
where: 
XXXXX 
is the five-character terminal identification 
VVVV 
is the four-character verb 
@ 
is the end-of-transmission character (X'26') 
$ 


is the system separator character as defined for the 
installation. 


The preformatted message constructed by a subsystem must be 
prefixed with the standard message header for FESEND 


(MSGHRSCH=X'00' ,MSGHRSC=X'00' , VMI=X'57'). This message is passed to 
the Front End via FESENDC (see Chapter 9) and the LOCK or UNLK takes 
place. No response message is sent to the terminal when such 


processing is requested by a subsystem. 
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Chapter 9 


USING INTERCOMM SERVICE ROUTINES AND FACILITIES 


9.1 SERVICE ROUTINE INTERFACING 


PL/1 programs may call Intercomm service routines directly using 
the standard CALL statement. The service routines must be defined with 
ENTRY OPTIONS (ASM INTER) to generate an Assembler Language parameter 
list for the called routine. The member PLIENTRY is provided for 
copying into PL/1 programs (use “INCLUDE PLIENTRY), which defines all 
standard Intercomm routine entry points (entry point names are given in 
the REENTSBS illustration, Figure 43). Special facility entry points 
may be added by the user. For dynamically loaded programs, linking the 
program with INTLOAD (required if program may be loaded above the 16M 
line under XA or ESA) will reduce dynamic linkedit processing at 
Intercomm startup. 


Specifications and coding criteria for user subroutines are 
described in Section 7 of this chapter. 


9.1.1 PL/1 Interface Routine (PMIPL1) 


PMIPL1 (see also Chapter 3) is a PL/1 interface routine which may 
be called by PL/1 programs for service routine and user subroutine 
interface. When only PMIPL1 is called, dynamically loaded programs 
(even if loaded above the 16M line under XA or ESA) do not need to be 
linked with INTLOAD. The application program calls PMIPL1 specifying 
which routine is to be called (system service routine or user 
subroutine) and the appropriate parameters to pass to it. PMIPL1 
preserves the PL/l1 environment and performs mode switching if the 
caller is in 3l-Amode. PMIPL1 also acquires a storage area in which it 
Saves the entry parameters for the called program. PMIPL1 then calls 
the specified routine, and on return, PMIPL1 restores the caller's 
environment and returns to the calling program. Coding format: 


CALL PMIPL1(routine-code, parameters) ; 
where: 
routine-code indicates the routine entry to be called. 


parameters is the actual parameter list to be passed to the 
called routine. All parameters passed to PMIPL1 must be in non- 
arithmetic format (locator/descriptors). PMIPL1 then passes the 
addresses in Assembler Language format except if the called 
subroutine is PL/1. All parameter addresses are validated for 
24-Amode. If the calling subsystem (or subroutine) may be loaded 
above the 16M line under XA or ESA, then all parameters must be 
in the caller's DSA (have a 24-Amode address). 


Routine-codes name halfword offset values into the REENTSBS table 
of routine addresses. Offsets 0 through 100 are reserved for Intercomm 
system routines. Offsets 104 and up may be used for other service 
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routines and user subroutines (in increments of 4). Figure 43 lists 
the routine-codes assigned as identifiers for Intercomm service 
routines in the released REENTSBS table. The member (of routine-codes) 
for copying into PL/1 subsystems and subroutines is named PENTRY (use 
ZINCLUDE PENTRY) and is illustrated in Appendix B. See also Appendix D 
for sample coding using PMIPL1 and the PENTRY table. The routine-codes 
may be in Static storage for 31-Amode programs. 


EENTSB1 CSECT 


NEGATIVE OFFSETS ARE USED BY SPECIFYING AN OFFSET ENDING IN B'l1l’, 
WHICH IS INCREMENTED BY 1 AND COMPLEMENTED TO OBTAIN TRUE OFFSET 
BY COBREENT AND PMIPL1. 

SUBMODS NAME=INTSORTC OFFSET -100,CODED AS 99 

SUBMODS NAME=DWSSNAP OFFSET -96,CODED 

SUBMODS NAME=MAPFREE OFFSET -92,CODED 

SUBMODS NAME=FECMRLSE OFFSET -88,CODED 

SUBMODS NAME=FESEND OFFSET -84,CODED 

SUBMODS NAME=FESENDC OFFSET -80,CODED 

SUBMODS NAME=ALLOCATE OFFSET -76,CODED 

SUBMODS NAME=ACCESS OFFSET -72,CODED 

SUBMODS NAME=MAPURGE OFFSET -68,CODED 

SUBMODS NAME=MAPCLR OFFSET -64,CODED 

SUBMODS NAME=MAPEND OFFSET -60,CODED 

SUBMODS NAME=MAPOUT OFFEST -56,CODED 

SUBMODS NAME=MAPIN OFFSET -52,CODED 

SUBMODS NAME=INTUNSTO OFFSET -48,CODED 

SUBMODS NAME=INTSTORE OFFSET -44,CODED 

SUBMODS NAME=INTFETCH OFFSET -40,CODED 

SUBMODS NAME=FECMFDBK OFFSET -36,CODED 

SUBMODS NAME=FECMDDQ OFFSET -32,CODED 

SUBMODS NAME=QWRITEX OFFSET -28,CODED 

SUBMODS NAME=QREADX OFFSET -24,CODED 

SUBMODS NAME=QWRITE OFFSET -20,CODED 

SUBMODS NAME=QREAD OFFSET -16,CODED 

SUBMODS NAME=QCLOSE OFFSET -12,CODED 

SUBMODS NAME=QOPEN OFFSET -8,CODED AS 7 

SUBMODS NAME=QBUILD OFFSET -4,CODED AS 3 

ENTRY REENTSBS 

DS 0A ALLOW FOR NEGATIVE OFFSETS 

DC A(REENTEND-REENTSBS -4) REQUIRED 

SUBMODS NAME=SELECT CODE 4- FILE SELECT 

SUBMODS NAME=RELEASE CODE 8- FILE RELEASE 

SUBMODS NAME=READ CODE 12- FILE READ 

SUBMODS NAME=WRITE CODE 16- FILE WRITE 

SUBMODS NAME=GET CODE .20- FILE GET 

SUBMODS NAME=PUT CODE 24- FILE PUT 

SUBMODS NAME=RELEX CODE 28- RELEASE EXCL. CONTROL 

SUBMODS NAME=FEOV CODE 32- FILE FEOV 


(Codes 36-64 
are reserved) 


Figure 43. PMIPL1 Routine Pointers (REENTSBS) (Page 1 of 2) 
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SUBMODS NAME=COBPUT CODE 68- COBOL MESSAGE SWITCHING 

SUBMODS NAME=MSGCOL CODE 72- MESSAGE COLLECTION 

SUBMODS NAME=COBSTORF CODE 76- COBOL STORFREE 

SUBMODS NAME=CONVERSE CODE 80- CONVERSE 

SUBMODS NAME=DBINT CODE 84- DATA BASE REQUEST 

SUBMODS NAME=LOGPUT CODE 88- LOGPUT 

SUBMODS NAME=PAGE CODE 92- PAGE ROUTINE 

SUBMODS NAME=GETV CODE 96- VSAM GET 

SUBMODS NAME=PUTV CODE 100-VSAM PUT 
FREER KEE ERE REE EERE ERR KERERRERE KEKE ERE EKER ERERER 
* INSERT USER SUBMODS MACROS HERE * 
KKH KA KK KKK KEKE KEKE KEK RK KEKE KEKE EKER ERK KEE EERE KEE RERERRRREREER 

COPY USRSUBS 

EQU * REQUIRED AFTER LAST SUBMODS 

ENTRY REENTEND 

CSECT 

END 


Figure 43. PMIPL1 Routine Pointers (REENTSBS) (Page 2 of 2) 


9.2 INTERSUBSYSTEM QUEUING (COBPUT) 


COBPUT (also used by COBOL programs) is called to queue a message 
for a user or Intercomm subsystem. Queuing is controlled by the 
Receiving Subsystem Code fields in the message header. If segmented 
input messages may be processed, set the MSGHQPR field in the header to 
C'2' before calling COBPUT. If the Edit Utility is used in the system, 
ensure the VMI field (MSGHVMI) is non-zero so that an attempt to edit 
the message for/by the receiving subsystem is not made. 


Coding format: 
CALL COBPUT (message, return-code) ; 
where: 


message is the label of the first position of the message 
(header + text) to be queued 


return-code is the label of a two-byte character field where 
COBPUT will place a return code. 


COBPUT copies the message to be queued to a new area of dynamic 
storage, converting variable character format message text and header 
fields as necessary if the Receiving Subsystem Code is for the Output 
Utility (see Figure 34). COBPUT then calls Message Collection (MSGCOL) 
to accomplish the queuing of the message. Figure 44 lists COBPUT 
return codes. 


The original message remains in the calling program's Dynamic 


Storage Area (DSA). If the message has not been processed or queued 
succesSfully, the subsystem may attempt to recover, or simply return to 
the Subsystem Controller with a return code of 8 or 12. Figure 45 


lists various alternatives. 
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Return Code Meaning 


Message queued successfully 


For Multiregion Facility users sending a message 
to another region, this return code signifies that 
the message was queued for sending to that region. 


Item code, length, or line number greater than 255 in 
variable character data item prefix (Output Utility) 


No room on subsystem queue or msg rejected for delayed 
subsystem--an entry was made on the system log 
(MSGHLOG=X' FC’) 


COBPUT has detected a message length too short to 
convert character item codes and lengths 


Invalid subsystem code--an entry was made on the system 
log (MSGHLOG=X' FB‘) 


DVASN system routine could not reserve a device (on first 
segment of multi-segmented messages only) 


A non-zero return code means the message was neither 
queued nor processed. 


Figure 44. COBPUT Return Codes 


A 


Return Code Alternative Action 
02, 06, 10, Program error: no recovery action. Correct the 
invalid fields and recompile program. 


Requeue the original input message for reprocessing 
by the currently executing subsystem via calling 
COBPUT referencing the input message and the 


currently executing subsystem, or follow action for 
Return Code 28. 


No recovery action: return to Subsystem Controller 
with return code 12. 


Attempt a time delay and call COBPUT to attempt 
queuing of the message again. 


Figure 45. Recovery From COBPUT Errors 
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9.3 INPUT MESSAGE SWITCHING (MSGCOL) 


COBPUT is called to queue an output message to activate another 
subsystem. It copies the message from the Dynamic Storage Area of the 
calling subsystem to a new dynamic area and calls Message Collection. 
Thus, the output message area within the Automatic storage of a 
subsystem is reusable upon return from COBPUT. 


The logic of an application subsystem might be such that the 
input message is modified within its dynamic area to become an output 
message to switch to another subsystem. To do this, the length of the 


input message may not be increased (data may not be added). If the 
length is shortened by 8 bytes or more, see the next section on freeing 
the remainder, and adjusting MSGHLEN in the header. Queuing the 


message for the next subsystem is then done by calling Message 
Collection (MSGCOL), instead of COBPUT; Message Collection then owns 
and is responsible for the management of the message area. All queuing 
is controlled by the receiving subsystem code fields (MSGHRSCH and 
MSGHRSC) in the message header. When returning to the System Monitor, 
the subsystem return code must be set to 900 (see Figure 14). 


Coding format: 


CALL MSGCOL(message) ; 
where: 


message is the label of the input message to be queued. 


MSGCOL return codes indicate the result of the queuing. The 
return code (stored in the Register 15 field of the caller’s save area) 
may be accessed by the PLIRETV ‘built-in-function’. (See Figure 46.) 


If MSGCOL is called via PMIPL1, a return-code field may be provided - 
see Apenddix D. Regardless of the result, the calling program no 


longer has any control over the area of dynamic storage occupied by the 
input message and must return a code of 900. 


SE ee ee ee ea = SS ee SS SS ES SS ee 


Return Code Meaning 
Message queued successfully 


No room on queue (entry made on system log) 
or message rejected for delayed subsystem 


No core for disk queue I/O area 


I/O error on disk queue 


Invalid subsystem code (entry made on system log) 


Figure 46. Message Collection Return Codes 
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Recovery action for unsuccessful queuing might be to return to 
the System Monitor with a return code of 8 or 12. A message would then 
be sent to the terminal that originated the input message being 
processed, 


9.4 FREE DYNAMIC (MESSAGE AREA) STORAGE (COBSTORF) 


COBSTORF may be called to free some of the area utilized for the 
input message before it is passed to another subsystem, or to free the 
entire message when it is not to be freed by the Subsystem Controller 
when the subsystem returns. COBSTORF may also be used to free an area 
passed to a PL/1 subroutine which was dynamically acquired by a calling 
Assembler Language program. 


Coding format: 
CALL COBSTORF(area, length) ; 
where: 


area is the name defining the first (leftmost) position of the 
area to be freed. 


length is the name of an aligned fullword (FIXED BIN(31)) 
containing a binary value indicating the number of bytes to free. 


CAUTION: Dynamic storage is managed as doublewords. The area 
specified should be aligned on a doubleword boundary 
(COBSTORF will round up the address if not). The 
length specified should be a multiple of 8 (COBSTORF 
will round down the length if not). When freeing 
part of an input message, only the rightmost portion 
may be freed and the rounded remaining length must be 
stored in the first two bytes (MSGHLEN) of the 
message header. If freeing all of the input message 
area, the subsystem must return to the Monitor with 
the return code 900.” 


A further clarification is provided in the previous section on 
message queuing via MSGCOL. 
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9.5 SEND MESSAGE TO FRONT END (FESEND) 


FESEND is called to pass a message to the Intercomm Front End for 
transmission to a terminal. The message header field MSGHTID specifies 
the destination terminal or broadcast group name. The entry point 
FESENDC of FESEND is used by high-level language subsystems. FESENDC 
copies (from the caller’s DSA) the message to be passed to the Front 
End to a new area of storage and proceeds via logic in the program 
FESEND. FESEND then requests queuing of the message on the associated 
terminal queue. If a broadcast group is specified, FESEND creates an 
individual message for each terminal of the group and requests queuing 
for each of those messages. All terminals in the broadcast group must 
be of the same type, as defined in the Back End Station and Device 
tables (see Chapter 2). 


FESEND accepts two types of messages: preformatted (VMI=X'57') 
message text, which contains the control characters and data for 
transmission to the terminal except for start-of-text sequence(s) to be 
added by the Front End; and fully-formatted (VMI=X'67') message text, 
which contains all control characters and data ready for transmission 
to the terminal. (MMU produces fully-formatted messages.) If 
segmented input messages may be processed, set MSGHQPR to C'2' before 
calling FESENDC. If passing the message to the Front End is for any 
reason unsuccessful, the subsystem is notified by a return code, and 
recovery action may be taken. 


FESEND tests whether messages sent to the Front End might be 
system commands or for control purposes. Such messages control Front 
End operation and generally cause no output to a terminal. Front End 
Control Messages (FECMs) are described later in this chapter. All 
system control commands and message text contents are documented in 


System Control Commands. 
Coding format: 
CALL FESENDC (message , return-code[option-codes] ); 
where: 
message is the label of the output message (header and text) 
to be passed to the terminal queue. 
return-code is the name of a two-byte character field where 


FESENDC will place a return code indicating whether or not 
processing was successfully completed. 
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option-codes is an optional four-byte character field -, 
containing Front End processing codes as follows: 


Byte 1: CRT Release option code: 
blank or X’00’--do not release (prevent screen 
overlay) next message (default) 
C'R'--release (allow overlay) next message to CRT 
C'C’--release next message, but do not cancel 
Front End conversational time-out 


Byte 2: VTAM Response option code (overrides Front End 
Network Table definition for terminal): 
blank or X'00’--no override (default) 
C'O’--Dl response 
C'E’--El response 
C'F’'--D2 response 
C'G'--E2 response 


Bytes 3 and 4; Not used (set to blanks or binary zeros) 


FESENDC return codes and possible recovery actions are listed in Figure 


47. A nonzero return code means the message was not queued for the 
Front End. Return codes 16-24 should only occur during subsystem 
testing. 


a a Se SS SS Se se Se ee ee ee a eS 


Return Code Meaning ) 


Queue-full condition encountered; attempt a retry 
by invoking FESEND again. 


Low-core condition encountered; attempt a retry 
by invoking FESEND again or return to Intercomm. 


I/O error (see Figure 14) encountered on disk 
queue; return to Intercomm. 


Invalid terminal-ID; no recovery action required. 
Check with System Manager to verify terminal/ 


Invalid message header; return to Intercomn. 
See also error message MG602I and Snap 51. 


Figure 47. FESENDC Return Codes 
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c 9.6 USER LOG ENTRIES (LOGPUT 


An application subsystem may require entries on the system log 
for many different situations: 


e Application-dependent security violation or other error 
recording. 


e Log entries rather than snaps used to trace the progress of a 
message while testing. 


e Any application-oriented requirement for a record on the 
system log. 


e Before- and/or after-image records of file updates (if not 
using the Intercomm File Recovery special feature). 


User log entries are identified by unique codes in the message 
header log code field (MSGHLOG) and hence can be recognized by any 
batch program processing the log off-line. Messages to be logged 
consist of a standard 42-byte header and message text. The log code 
field (MSGHLOG) in the message header must be set to any value from 
X'41' to X’6F’. Logging is performed by calling the Intercomm system 
service routine LOGPUT. The date and time stamp in the message header 
(MSGHDAT and MSGHTIM) will be updated by LOGPUT prior to writing to the 
log. Log entries may subsequently be suppressed for later Intercomm 

c executions by modifying the LOGTROUT translate table in the LOGPUT 
routine. Any message having a log code in the header which translates 
to X'FF’ will not be logged. 


The length of the record on the log is controlled by the value of 
MSGHLEN in the message header and must be at least 42. LOGPUT will not 
write out messages longer than the logical record size of the log (see 
INTERLOG JCL description in the Operating Reference Manual). 

Coding format: 
CALL LOGPUT (message) ; 


where: 


message is the label of the message (header plus text) to be 
logged. 


There is no return code from LOGPUT. 
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9.7 CALLING USER SUBROUTINES FROM PL/1 SUBSYSTEMS 


All subroutines called by an application subsystem may be called 
directly or via PMIPL1. Under XA or ESA, passed parameter values must 
be in 24-Amode storage (such as the caller's DSA) if the routine is 
called via PMIPL1 or if it is resident or loaded in 24-Amode. No other 
special conventions need be followed in order to call: 


e An Intercomm system service routine. 

e A user-coded Assembler Language (BAL) subroutine. 
e A user-coded PL/1 subroutine. 

e A data base interface routine. 


If the routine is called directly, passed parameters must be 
appropriate to the language of the routine, for example, to pass a 
structured area to a PL/1 subroutine declare a pointer to the area and 
pass the pointer, whereas the label of the area may be passed to a BAL 
program. 


The Intercomm return code area may be used as a parameter to pass 
a return code back to the calling PL/1 subsystem. The subsystem may 
pass that return code back to the Intercomm Monitor (if standard 
Intercomm return code conventions are used by the subroutine) or may 
take action based on the return code and then change the passed value 
in the return code area to a standard Intercomm return code value. See 
the sample programs in Chapter 10. If a subroutine is called via 
PMIPL1, all parameters must have non-arithmetic attributes, therefore 
in this case the Intercomm return code area may not be used. 


9.7.1 Defining User Subroutines to Intercomm 


Except as noted in Section 9.7.4, a user-coded subroutine 
(Assembler Language or PL/1) must be defined to Intercomm via coding of 
a SUBMODS macro in a user member USRSUBS which is copied at the end of 
the subroutine table REENTSBS (before REENTEND) at assembly time (see 
Figure 43). Resident, reentrant Assembler Language subroutines are 
defined by the NAME parameter of SUBMODS, all others via the LNAME 
parameter, plus additional parameters defining language, residency, 
etc. Additionally, the routine’s reference name and corresponding 
index code should be added to PENTRY (see Appendix B) for easy access 
by subsystems when calling PMIPL1, or add the name to PLIENTRY if it is 
a BAL routine. The SUBMODS macro is described in Basic System Macros. 


9.7.2 Interfacing to User-Coded Assembler Language Subroutines 


Assembler Language subroutines must be coded as reentrant if they 
may give up control to the Intercomm Dispatcher (via I/O requests, MMU 


requests, message queuing, etc.). When called from a PL/1 program, 
standard linkage conventions are used. PMIPL1 (if used) issues a 
MODCNTRL macro to link to non-resident Assembler subroutines. At 


entry, register 13 points to a save area in the caller's DSA. 
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Therefore, the caller's registers must be saved on entry to the 
Assembler subroutine, and reloaded before return, and save area 
chaining must be done. The save area may not otherwise be used by a 
called subroutine. An Assembler subroutine may not call a PL/1 
subroutine (unless code is provided to pass the caller's PL/1 
environment). 


9.7.3 Interfacing to User-coded PL/1 Subroutines 


A reentrant PL/1 subroutine is coded like a PL/1 subsystem in 
that it uses OPTIONS (REENTRANT) and a Dynamic Storage Area (in calling 
programs ISA - do not use the MAIN option), and it may call PMIPL1 to 
interface to Intercomm service routines and other user subroutines, or 


it may use direct calls. Non-resident reentrant PL/1 subroutines 
loaded above the 16M line under Release 10 must use the coding 
conventions described in Chapter 3. Subroutine calls may be nested, 


but must return to the caller, as illustrated previously in Figure 5. 
See Appendix A for subroutine linkedit considerations. 


9.7.4 Interfacing When Caller or Subroutine is Non-Resident 


When all calls are made via PMIPL1, all called routines 
(Intercomm and user) must be defined in the REENTSBS table via SUBMODS 
macros as described earlier in Sections 9.1.1 and 9.7.1. If the called 
routine is reentrant BAL and resident in the Intercomm load module 
(NAME parameter used on SUBMODS coding), PMIPL1 calls the routine 
directly passing the address of the caller's save area in register 13. 
If the routine is non-resident or not reentrant BAL (LNAME parameter 
used on SUBMODS macro), PMIPL1 links to the subroutine interface module 
DYNLLOAD which loads the called routine if necessary before giving it 
control, again passing the original caller's save area address and 
registers 2-12. DYNLLOAD performs mode switching if the called routine 
is loaded above the 16M line under Release 10. Return is via DYNLLOAD 
to PMIPL1 which then returns to the caller by using a previously saved 
return address. 


When using direct calls between resident routines, the linkedit 
of the Intercomm load module resolves the external references, resident 
subroutines do not need to be defined in REENTSBS. To link to a loaded 
subroutine (must be defined in REENTSBS), a resident PL/1 program must 
either call it via PMIPL1 or call a resident BAL interface routine 
passing the name of the desired subroutine. The interface then issues 
a MODCNTRL macro to link to DYNLLOAD. If the desired subroutine is 
PL/1, the interface routine must pass the caller's registers 2 through 
13. See the sample interface program in Appendix E. 


For non-reSident PL/1l programs using direct calls, linking the 
loadable program with INTLOAD will resolve all Intercomm routine entry 
points (REENTSBS not needed). Otherwise, dynamic linkedit must resolve 
the called entry point addresses at Intercomm startup, which adds 
startup processing overhead. Dynamic linkedit is required for IBMB.... 


internal PL/1 subroutines linked in the Intercomm load module. Dynamic 
linkedit can also be used to resolve calls from 24-Amode programs to 
user subroutines in the Intercomm load module. Calls to loadable 


subroutines (which must be defined in REENTSBS) can be made via PMIPL1 
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or an interface routine (resident or linked with loaded calling PL/1 
program) as described above. If the calling program may be loaded 
above the 16M line, the interface program and INTLOAD must be linked 
with it (along with PLIV). 


Under Release 10, the need for a BAL interface routine (or PMIPL1 
calls) for loadable user subroutines (or for dynamic linkedit 
resolution for resident subroutines) can be eliminated for dynamically 
loaded PL/1 programs using direct calls. Define the user subroutines 
to REENTSBS by coding SUBMODS macros for them in the copy member 
USRSUBS. Always use the LNAME parameter even if defining a resident 
reentrant BAL subroutine. Then reassemble and link REENTSBS and 
reassemble and link INTLOAD so that they both copy the revised USRSUBS 
and thus entries are generated within INTLOAD for the directly called 
subroutines. Then link the loadable program with the revised INTLOAD. 
INTLOAD links directly to DYNLLOAD for 24-Amode callers or via the 
resident interface SWMODE for 31l-Amode callers (required). In both 
cases, the PL/1 environment is preserved for called PL/1 subroutines. 
Note that as new subroutines are defined in USRSUBS and copied to 
INTLOAD for new calls, older programs which do not call the new 
programs do not have to be relinked with the latest revised INTLOAD. 
Dynamic linkedit may still be used for resident IBMB... routines as 
they can be entered directly in 31-Amode (see also Appendix A). 


9.8 FRONT END CONTROL MESSAGES 


The Front End Control Message (FECM) facility provides three 
types of Front End control messages which may be used by application 
subsystems for: 


e Front End data queuing (FECMDDQ) 
e Front End feedback messages (FECMFDBK) 
e Front End queue release (FECMRLSE) 


A FECM is generated by an application program call to a service 
routine. The generated FECM message text is complete. The header 
field MSGHLEN has been set; bytes 3-42 are not modified. If the user 
has copied a valid header to the FECM message area prior to the call, 
only the sending subsystem codes (SSCH,SSC) and the VMI (X’57') must be 
set. The generated FECM must then be passed to the Front End by a call 
to FESENDC in the application program. 


After a call to any Front End Control Message facility, a return 
code is placed in the first byte of the status word: 


a Se Se es Se ee a ee ee ee ee ee ee 


Return Code Value Meaning 


oe Re ae ee: a SR SS 


FECM successfully created 


No storage for FECM processing (Assembler only) 
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9.8.1 Front End Data Queuing 


Front End data queuing (FECMDDQ) works in conjunction with the 
Dynamic Data Queuing Facility. It provides the user with a more 
efficient way of handling groups of related output messages. An 
application may pass a Dynamic Data Queue (DDQ) to the Front End via a 
FECM. The DDQ contains messages to be sent to a terminal. This is a 
more efficient design approach than sending one message at a time to 
the Front End via FESEND, and prevents interleaving of unsolicited 
messages with those on the DDQ. This feature is particularly useful 
for printed reports. The messages on the DDQ must be preformatted 
(VMI=X'57') or fully formatted (VMI=X'67'). The Dynamic Data Queuing 
Facility manual contains detailed information on DDQ concepts, 
facilities and implementation, and specific design considerations for 
Front End Data Queuing. MMU uses this facility (FECMDDQ), when 
requested for multipage printer output. 


Coding format: 
CALL FECMDDQ(status-word,fecm-area,ddq-id[ ,ddq-disp]); 
where: 


status-word is a 4-byte (fullword aligned) area required by the 


facility. 

fecm-area is a 112-byte area to contain the FECM (header and 
text). The user should initialize the header prior to the 
call, probably by copying the input message header to this 
area. 


ddq-id is the sixteen (16) byte DDQ identifier. 


ddq-disp is a one-byte code indicating DDQ disposition after all 
messages are transmitted: 


C'S’ means SAVE the DDQ (required if MSGHTID is a broadcast 
group name) 


C'F’' means FREE the DDQ (default) 


NOTE: The ddq-disp parameter may be omitted if the DDQ is to be freed 
after all the messages are transmitted (default). All of the 
above parameters must be in Automatic storage (DSA) if the 
calling program is loaded above the 16M line under XA or ESA. 


9.8.2 Front End Feedback Messages 


This type of FECM (FECMFDBK) is used by an application to 
determine that all prior messages queved for a terminal (before the 
FECM) have been transmitted. In this way, an application subsystem can 
be notified that certain critical messages have indeed been 
successfully transmitted. 
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Subsystem logic creates all normal output messages and passes 
them to the Front End (via FESEND, MMU, or by queuing messages for 
Output). Generation of a feedback message is then requested by a call 
to a FECM service routine. The feedback message is then processed in 
the same way as the other messages for the terminal (queued via FESENDC 
or the Output Utility). When the Front End retrieves the feedback 
message, it is routed to the subsystem specified when the feedback 
message was generated rather than to the destination terminal. 


Feedback messages may also be used in conjunction with Front End 
Data Queuing. A feedback message could be an intermediate, or the 
last, message on a DDQ passed to the Front End. If the DDQ was created 
via MMU (a MAPEND call option), then the feedback FECM must be created 
and queued by the subsystem on return from the MAPEND call. 


Coding format: 
CALL FECMFDBK(status-word, fecm-area, fecm-rsc,fecm-text); 
where: 


status-word is a 4-byte (fullword aligned) area required by the 
facility. 


fecm-area is a 78-byte area to contain the FECM (header and text). 
The user should initialize the header area prior to the call, 
probably by copying the input message header to this area. 


fecm-rsc is a two-byte receiving subsystem code (high/low) to 
specify the feedback message destination subsystem. 


fecm-text is a 16-byte area containing the desired feedback 
message text. 


9.8.3 Front End Queue Release 


This type of FECM (FECMRLSE) allows the subsystem to override the 
normal Front End Logic for CRTs, which requires a one-for-one 
correspondence between input and output messages. When the release 
FECM is processed by the Front End, it causes a subsequent response 
message queued for the same terminal (as identified by MSGHTID in the 
FECMRLSE message header) to be transmitted immediately, rather than 
waiting for input (RLSE command) from the terminal operator. Because 
of protocol restrictions (HDFF) on VTAM Front End IBM SDLC 3270 CRT 
processing, the CRT release option for the first call to FESEND should 
be used (see Section 9.5) as a release; because if the terminal is 
already in send mode, it is necessary to turn the line around before 
sending the released message, which may confuse the terminal operator. 
The CRT release option locks the terminal in receive mode, preventing 
new input by the operator. 


A release FECM might be used if a subsystem queues more than one 
output message to the CRT terminal due to a considerable amount of 


processing (file/data base I/O) being necessary between messages. The 
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first message might be an immediate response to the terminal operator 
indicating the input request is being processed, but allowing new input 
by the operator. Then, the second message (following the release FECM) 


is the ultimate result of the requested processing. A release FECM 
could also be used to force immediate transmission of a critical 
message to another CRT (other than the input terminal). Such 


processing should be used with caution because unsolicited messages can 
cause confusion for the terminal operator and may clear an existing 
screen format or displayed message. Coding format: 


CALL FECMRLSE(status-word, fecm-area); 
where: 


status-word is a 4-byte (fullword aligned) area required by the 
facility. 


fecm-area is a 60-byte area to contain the FECM (header and text). 
The user should initialize the header area prior to the call, 
probably by copying the input message header to this area. 


9.9 IN-CORE TABLE SORT FACILITY (INTSORT) (Release 10 only) 


To sort an in-core table, the INTSORT Facility (entry point 
INTSORTC for PL/1) is provided. Such a table might be data stored ina 
Store/Fetch string or file data record via online transactions or 
offline processing. The table can have any number of fixed-length 
entries up to 32767, and each entry can have a total size of 1 to 255 
bytes. The key to be sorted on can be anywhere within the entry, but 
must be in the same place, and of the same length, in each entry. 
Coding format: 


CALL INTSORTC(entries,entry-length,table,key-offset, 
key-length, return-code); 


where: 


entries is a 4-byte (fullword aligned) area containing the number 
of table entries (up to 32767) in binary format, 


entry-length is a 4-byte (fullword aligned) area containing the 
size of each entry (up to 255) in binary format. 


table is the name of the area containing the table to be sorted. 


key-offset is a 4-byte (fullword aligned) area containing the 
offset (-1) in binary format of the key within each entry (value 
must be zero if at the beginning of the table entry; 1 if it 
starts in the second position of the table entry, etc.). 


key-length is a 4-byte (fullword aligned) area containing the 


length in binary format of the key (to be sorted on) of each 
entry (can be the same as entry-length). 
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return-code is a 4-byte (fullword aligned) area to contain the 
return code (in binary in the low-order byte) from INTSORTC, as 
follows: 


a 


Meaning 


INTSORT completed successfully 


The key-length plus key-offset exceeds maximum (255) 
entry-length. 


For all non-zero return codes, the sort is not executed. 


9.10 OTHER INTERCOMM SERVICE FACILITIES 


The following service routines for application programs are 
accessed via the following subroutine entry names listed in REENTSBS: 


e MMU (MAPIN, MAPOUT, MAPEND, MAPCLR, MAPURGE, MAPFREE) 

e Store/Fetch (INTSTORE, INTFETCH, INTUNSTO) 

e DDQ (QBUILD, QOPEN, QREAD, QREADX, QWRITE, QWRITEX, QCLOSE) 
e Page Facility (PAGE) 

e DBMS (DBINT) - data base interfacing 

e Dynamic File Allocation (ALLOCATE, ACCESS) 


Code names for the routines are provided in the members PLIENTRY and 
PENTRY (see Appendix B). Detailed documentation for use of the above 
facilities is provided in separate manuals (see Chapter 2). Special 
coding and call conventions for specific data base support are 


described in Data Base Management System Users Guide and vendor 
manuals. 


Other service routines described for Assembler Language 
programmers in the Assembler Language Programmers Guide such as binary 
table search, ESS user-id search, dispatcher related routines, and data 
field search routines (when Edit and Output Utilities used), can be 
called directly from PL/1 programs (declare entry name as ENTRY OPTIONS 
(ASM INTER), or add the entry name to USRSUBS with a SUBMODS macro (use 
NAME parameter only) and add the name and offset code to PENTRY if 
PMIPL1 called. 
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9.10.1 Features Accessible via Assembler Macros 
Several Intercomm facilities are accessible only via a call _to an 
assembler-coded subroutine which issues an Intercomm macro to use the 


facility. Such features include: 


e Enqueue/Dequeue--to request exclusive or shared control of a 
resource (INTENQ, INTDEQ) 


e Start/Stop--function control or status test (SSSTART, SSSTOP, 
SSTEST) 


e Write-to-operator--to issue a message to the CPU console 
(PMIWTO, PMIWTOR) 


e Snap--to issue a snap of the passed program areas for 
debugging if DWSSNAP not used (Release 10 - see Chapter 3) 
(PMISNAP) 


e Timed wait--to request a timed delay of subsystem processing 
if IJKDELAY not used (see Chapter 2) (INTWAIT) 


e Asynchronous processing--dispatch a time-delayed routine, 
post or wait on an asynchronous processing routine (DISPATCH, 
INTPOST, INTWAIT) 

e Acquire current time and/or date (INTTIME, GETDATE) 


e Acquire device-dependent information about a terminal 
(EXTERM) 


e Track user accounting information for SAM (USRTRACK) 
e Convert a hexadecimal field to printable character (LAYOUT) 
e Format subsystem codes for printing (SSCONV) 


e Test authority of the currently signed-on (under ESS) user to 
use a logical function, such as Data Base access (SECTEST). 


Note that use of most of these facilities will add to subsystem 
processing time (increase TCTV). Further documentation may be found in 


the Assembler Language Programmers Guide and Basic System Macros. 


NOTE: GETDATE may only be used under Release 10, 
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SAMPLE PROCESSING PROGRAMS 


The sample program SQPLIA, shown in Figure 48, demonstrates 
coding of a PL/l subsystem which is either resident or dynamically 
loadable above or below the 16M line (if XA or ESA). The program 
processes an inquiry transaction (TPL1) containing a part number and a 
warehouse number for a stock status display. MMU is used to transform 
the incoming message into a fixed field format. The part number is 
transformed into a RBN for accessing a BDAM part description file 
(PARTFILE). The RBN and a part description record area are passed as 
parameters to a called PL/1 subroutine SQPL1B, illustrated in Figure 
49, which also may reside above or below the 16M line. The subroutine 
retrieves the requested record from PARTFILE and passes back the File 
Handler return code to the calling subsystem via the Intercomm return 
code field. 


Together, the part number and warehouse number provide a VSAM key 
for accessing a stock status file (STOKFILE). The File Handler is used 
for accessing both files. MMU is used for formatting an output 
display. Error messages, for conditions such as non-existent or 
erroneous warehouse or part numbers, or file I/O errors, are built 
within the program and formatted by MMU using an error map area. 


The PLIENTRY and PLMSGHD source text members defining the service 
routine entries and Intercomm message header fields are % INCLUDE'd 
from the source text members by the PL/1 compiler. The PLILOGCH source 
text member used for terminal attribute and command override for MMU 
processing, and the symbolic map areas, are also copied into the 
program. Note that the MMU symbolic map areas are BASED on PTR_mapname 
and that the pointers are set up in the program (MAPIN called directly 
with five parameters). Note also that the first three input parameters 
to the program are declared as pointers. 


All required table entries, JCL, sample input messages and 
testing procedures, plus sample execution output, are illustrated in 


Chapter 11, "Subsystem Testing.” The subsystem code used in the 
SYCTTBL macro to identify the sample subsystem is PQ. Intercomm's BTAM 
simulator is used for testing. Test messages are included to test as 
many error combinations as possible. Chapter 12 illustrates a similar 


subsystem (without the PL/1 subroutine) coded for the same purpose but 
using the Edit and Output Utilities, a COBPUT call, and Test Mode for 
testing. 
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STMT LEV KT 


/* PROCEDURE 


SQPL1As PROC 


DCL 


OCL 


Figure 48. 


Sample Processing Programs 


SQPLI1A TO IACUIRE CN STUCK/PART FILES FOR MSG RESPONSE 


CINIMSG_PTRySPAySCT RC) 

OPTIUNS(MAINsREERTRANT)} /* SUBSYSTEM 'PG* - IACUIKY 
/* DEFINE THE INCOMING PARAMETERS 

CINIMSGLPTR, 7* INPLT PARP 1 = INPLT MSG POINTER 

SPA» 7* INPLT PARP g = SYSTEM PARAM AREA 

SCT) PTR; 7* INPLT PaRm 3 = SUBSYSTEM ENTRY 

RC FIXED EINC21)3 /* iNPLT PAKF 4 = RETURN CODE 


S@PL16 ENTRY EXTERNAL; ye eeeeeee CEF SUPLIB ENTRY 


/* CEFINE ALL STATIC STORAGE VARIABLES 


1 MAPLRAMES STATIC, 7* FCR CALLS TC MPL 


3 JGLMAPGRCUP CHAR(E) INITU'STKSTAT')» /* MAPGRCLP 
3 ICLMAP CKAR(8) INITUTMEAPI') 5 /* NORPAL BAP 
3 ERROR_MAP CraR(@) INITCTERRPAFT); /* ERROR MAF 


2 FILELNAMES STATIC, 7* FCR CALLS TO ThE FILE FAnCLERK 


3 CCLSTCCK CHAR(E) INITO*STCKFILE' IDS 


3 ULLPARY CHARCE) INITOC'PARTFILE') MCVED TC SUPLic 


Sample PL/1 Subsystem SQPLIA (Page 1 of 18) 
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STMT LEV AT 


Sample Processing Programs 


7*® INCLUDE PLIENTRY = DEFIAES ICOM ENTRY PCIATS = AS ASP INTER ¢/ 


ZINCLUDE PLIENTRY se Poors e eo eee eee eee eee HTH RETO TEH EHS HT OTEK HEE VE RES. 


1 O CECLARE ( SELECT, 
RELEASE, 
READ, 
WRITE) 
GET» 

PUT) 
GETV» 
PUTV, 
RELEX) 
FEQV, 
CUBPUT, 
MSGCCL» 
FESEND, 
FESENDC, 
COBSTORF , 
CONVERSE» 
LOGPUT» 
OBINT, 
PAGE, 
QBLILD»s 
COPEN» 
CREAD, 
CREADA, 
OnRITE,s 
QnRITEX, 
CCLUSE,» 
FECMDDCG, 
FECMFOBKy 
FECMRLSE, 
PAPIN, 
PaPCLT, 
MAPFREE» 
MAPENL» 
PAPURGE, 
FAPCLinKYy 
CnSSNaAPy 
INTSGRTCs 
INTSTORES 
INTFETCE> 
INTUNSTC) 


PRS T EOP ET ETE EEE 


/* REL IC es 
/* REL 1C #7 


ENTRY CPTICNS CASK INTERK)3 
7* FOR CIRECT CacLS TO ICP AND USER RCUTINES #7 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 2 of 18) 
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STMT LEV AT 


/* INCLLCE PLILCGCh = MMU SYMBCLICS */ 


ZLINCLUDE PLILOGCHj POFFO eee eee ae eee eee ee OH HOO HOE OE TEETH EEE ETTORE DED 


CECLARE ALKFPRMUT CRAR(1) STATIC INIT(U® "05 
CECLARE ALKFRKEY CHAR(1L) STATIC IhITO* "05 
DECLARE ALRMRMKY CrAR(1) STATIC INITO® "D5 
DECLARE PRNTNL ChAwKO1) STATIC INITC® "95 
CECLARE PRNT4&C CrAK(1) STATIC INTO" "93 
CECLARE PRNTO4 CRAK(1) STATIC IRITC® "95 


8 1 0 DECLARE UAN CHAR(1) STATIC INITO® "95 
9 1 © DECLARE UANMCT CHAR(1) STATIC INITC® "95 

10 1 OO DECLARE UANSEL CHAR(1) STATIC INITC® "5 
ll 1 0 DECLARE UANMDSEL CHAK(1) STATIC INITC' "D5 
12 1 0 OECLARE VAHSEL ChAR(1) STATIC INITOC® 893 
13 1 ©O DECLARE UAHMESEL CHAR(1) STATIC INITOCS "05 
14 1 0 DECLARE VAX ChAR(1) STATIC INITO' D5 
15 1 0 DECLARE LAXMET CHAR(1) STATIC INITO" °)5 
16 1 O DECLARE UNN CRAR(1) STATIC INITO® "05 
17 1 O DECLARE UNNMFCT CRHAKE1) STATIC INITC® "95 
18 1 © DECLARE LNNSEL CHAR(1) STATIC INITO® "95 
19 1 0 BECLARE UNNMDSEL CHAR(1) STATIC INITO® "03 
20 1 0 GECL4RE UNHSEL CHAR(Gi) STATIC INITiS "D5 
21 1 O CECLARE UNHPCSEL CHAR(L) STATIC INITO® "D3 
22 1 0 DECLARE UNX CHAR(1) STATIC INITO® "D5 
23 1 OQ DECLARE UNXMCT CHAR(1) STATIC INITO' "D5 
24 1 O CECLARE PAN CFAR(1) STATIC INIT(S "D5 
25 1 0 LECLARE PANFCT CrhAk(1) STATIC IKITE® "D5 
26 1 0 GECLARE PANSEL CHAK(1) STATIC INIT(S °);5 
27 1 O DELLARE PANMOSEL CHAK(1) STATIC INITC® "95 
26 1 0 CECLARE PAHSEL ChAK(1) STATIC IAITC® "95 
24 1 0 CECLARE PAHPCSEL CHAR(1) STATIC INITO® 903 
30 1 ©O DECLARE PAX CFKAR(1) STATIC INITC(® "95 
31 1 QO DECLARE PAXPCT CHAK(1) STATIC INIT(® "05 
32 1 ©O DECLARE PSH CrsR61) STATIC INITO® "D5 
33 1 0 CECLARE PSNPOT CHAR(1) STATIC INITC® "D5 
34 1 O CECLARE PSNSEL CréAk(1) STATIC IBITOUT "035 
a5 1 0 DECLARE PSNPCSEL CHAR(1) STATIC IAITO" "D5 
36 1 0 BECLARE PSHSEL CHAK(1) STATIC IN]TCS "2; 
37 1 0 CECLARE PSHFDSEL CHAK(1) STATIC INITCS "5 
38 1 O VLECLARE PSX CkAR(1) STATIC INITO* 903 
39 1 O DECLARE PSXFCT ChAk(1) STATIC INITCP "D5 
40 1 ¢C OECLARE SUPR ChAR(1) STATIC INITC? "95 
41 1 O DECLARE wRITEL CHAK(1) STATIC INITC® "D5 
42 1 O CECLARE ERASwHRIT CrAK(1) STATIC ISITE "05 
43 1 © VCECLARE ERASWRAL CrAK(1) STATIC INITC' "05 
44 1 O DECLARE KMOT CHAR(1) STATIC IAITOE® 805 
45 1 O DECLARE RKEYoD ChAK(1) STATIC INITC' "03 
40 1 0 DECLARE RMDTKEYB ChAnK(1) STATIC INITUS "05 
47 1 O CECLARE ALARF CHAR(1) STATIC IAITO® [05 

1 0 

1 0 

1 0 

1 0 

1 0 

1 0 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 3 of 18) 
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STMT LEV AT 


DECLARE PRNTYO CHAR(1) STATIC INIT 9)5 
CECLARE PRNLRMCT CHAR(1) STATIC INITC! 
CECLARE PR4CRMDT CHAR(1) STATIC INITE? 
CECLARE PR64kHOT CFAR(1) STATIC INITE? 
DECLARE PREORMCT ChAR(1) STATIC IAITGCE 
DECLARE PRNLRKEY CHAR(1) STATIC INITC?E 
CECLARE PR4CRKEY CHAK(1) STATIC IAIT¢* 
CECLARE PROE4RKEY CHAR(1) STATIC INITC! 
DECLARE PR&ECRKEY CHAR(1) STATIC INITC! 
DECLARE PRNLRMKY ChAR(1} STATIC INITC! 
DECLARE PR4CRMKY CHAR(1) STATIC IANITC! 
CECLARE PROE4SRMKY CHAK(]} STATIC INITC 
CECLARE PRSCKPKY CrAK(1) STATIC INIT(? 
CECLARE PRNLALRM CrFAR(1) STATIC IAITC! 
DECLARE PR4SOALKM CmAK(1) STATIC INIT(¢ 
CECLARE PRO4SALKM CHAK(1) STATIC INITC! 
CECLARE PRECALRM ChAK(1) STATIC INITC! 
CECLAR&k PRNLARMD CrAK(1) STATIC INITU® 
DECLARE PR4SOQARMD CrAR(1) STATIC INITC? 
CECLARE PRO4SARMD CrAK(1) STATIC INIT? 
CECLARE PR&CARMD CrAK(lid STATIC INITC!? 
DECLARE PRNLARKY CRAK(1) STATIC INITI# 
DECLARE PR4CARKY CrAR(1)} STATIC INITE! 
DECLARE PR6ESARKY CrAK(1) STATIC INIT(! 
CECLARE PRECARKY ChAR(1} STATIC INIT! 
DECLARE PRNLAMKY CrAR(1) STATIC INITCE 
DECLARE PR&CAMKY CréK( a} STATIC INITC! 
GECLARE PRO4SAMKY ChAK(1E STATIC IAITC! 
CLECLAR&e PROECAMKY CrAn(11] STATIC INITC? 
CECLARE NULL ChARK(1) STATIC INITC® "93 
VECLARE NL CFAK(L) STATIC ANITC® *9; 
UcCLARE FF CrAK(1) STATIC INITC® "93 
CECLARE CR CrA&K(1) STATIC INITO® §'93 
CECLARE S$] CrAK(1) STATIC INITCE® "93 
SOP SPEC REE SR EES 7* SYMECLIC CEWVICE LEPEACAAT CHARS USED BY FFL 8/ 


ee eee ee ee ee 
ee we we we we we we we we we we 


1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
a 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
ry 
2 


NooD0 909 G7NDODGGGOVCAOGDVACONDMCO Oc O90 COMCGC0CCAC0CaC9000 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 4 of 18) 


115 


Chapter 10 Sample Processing Programs 


STMT LEV NT 
/* DEFINE PESSACE STRLCTUKE IN EXTERNAL STORAGE *%/ 
88 1 #0 OCL 1 INPUT_MESSACE BASECCIN_MSG_PTR)» . 
/* INPLT FPESSAGE STRUCTURE */ 
3 IN_LHOR» /* “AP THE INPLT HCR #/ 
7* INCLLOE PLYSGED o/ 


ZINCLUDE PLPSGHD; Fee etter eee seer eee eres eee OTTO OHHH TO TEOET ET OED ERODE 
MSGRLEN FIXEC BIK(15) LRALICNED, 

MSGROPR CFAR (1)5 

PSGFRSChK BIT (8) ALIGNEU, 

MSGrRSC BIT (8) ALICKED, 

MSGHSSC BIT (8) ALIGKEC, 

MSGFFPMAN BIT (24) ALICNELs 

MSGFCAT CrAR (6€)5 

MSGFTIM Crak (8) 

MSGFTID CraR (5)5 

MSGRCON BIT (16) ALICNELs 

PSGFFLGS CrAR (2)> 

MSCFBMN BIT (24) ALICKELs 

MSGrSSCr EIT (8) ALIGNELs 

MSGRUSR CFAR (1)s 

RSGrADDR EIT (1) ALICNEC, 

PSCFLGG CrAk (1)5 

MSCFBLK B17 (8) ALIGKEL, 

MSGHYMI] BIT €6) ALICNEDs 

OUT TET E ETE EES /* STANCARC DEFINITICAN CF TRE HEADER FIELCS o/ 


VFIMWUMY FU UU UU 


3 INLTEXT; /* KOT REFERENCED %/ 
7* INPUT wILh BE REFERENCED &Y TRE FIELU NAMES CF TRE SYPBCLIC MEP #/ 


7* INCLULOE STKSTATEF / 


AINCLULE STKSTATP fee eee ee ee eee eer eee eee ee Hee E EERE TTS UKHO HERE SHOE RHEE 


8Y 2 ¢ CCL 1 MAP DASEL(PTR_MAP1) UNALIGNELC 


3 VERBF, 
4 vVERBL FIXEC BIN(15)5 /* LENGTH #7 
4 VERBT CrAkllly,y /* TAC ¥/ 
4 VERB CrAk lady 
2 PARKTNOF, 7* START STIRULCTURKEL SEGMENT *#/ 


3 PARTNCL FIXED BIN(15)5 /* LEACTR */ 
3 PAKTNCT CRARG1) 5 /* TaG #/ 
3 PAKTAC, 
4 FILLER PIC '(4)G5', 
4 RBNBYTE PIC 'S', 
2 LSEEIs 
3 wrSNOGF, 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 5 of 18) 
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STMT LEV NT 


4 wFSACL FIXED BINt15), /* LEKCTH 
4 wHSNOT CHAR(1)5 /* TAC #/ 
4 wHSNO PIC "999%, 

3 PRIDATAFy, 
4 PRTIDATAL FIXED BIN(15)5 /* LENGTH */ 
4 PRIDATAT CHAR(1), /% TAC #/ 
4 PRTDATA CHAR(54), 

3 CROUNTFs 
4 GRDUNTL FIXED BIN(15),5 /* LENGTH */ 
4 URDUNTT CHAR(1),5 /* TAC #/ 
4 ORDUNT CHAR(5), 

3 PRIPRCFs 
4 PRTPRCL FIXED BIKN(15), /* LENGTH */ 
4 PRTIPRCT CHAK(1), ¢* TAG FS 
4 PRTPRKC FIXED DECI 4)5 

3 wWrSLUCFs 
4 whSLOCL FIXED BIN(15)5 /* LENGTH */ 
4 wESLOCT ChaAR( 1), /*% TEE ¥F 
4 wHSLOC CHAR(22) 5 

3 STKLEVFs 
4 STKLEWL FIXED BING15)5 /* LENCTH */ 
4 STKLEWT CrHARG1), 22 TAC P/ 
4 STKLEY FIXED DECI7)» 

3 LEWDATEF, 
4 LEvDATEL FIXEC BIN(G15)5 /* LENGTH *%/ 
4 LEVDATET CriAkll), 7* TAG PS 
4 LEVDATE CHAK(b), 

3 STKOKOF, 
4 STKOROL FIXEC BIR (15), /* LENCTIN #¥/ 
4 STKOROT Crékll)s 7/7 TAC BF 
4 STKORD FIXEC DECI)» 

3 URCCATEF, 
4 GCROCATcL FIXEC BING(15)y) £* LENGIM #7 
4 CRUDATET CHékll)s /* TAC F/ 
4 URUDATE CHAR (OO) » 


gc FILLER CrArk(1); /* ENC CF FAP */ 
SO 1 ¢ DCL 1 EkRMEAP BASELUPTR_LER RMAF] LNALICRELD, 
3 ERRMSGF, 


4 ERRMSG. FIXED EIN(IE), /* LENGTR ¥/ 
4 ERKPSCT CHARI) 9 7* TAC *y 
4 ERKPSE CnAéKw (oC), 
Z FILLER = CraAR(L)3 se ENC CR PAP &/ 
See naeeeeneeeen ees Je TRE SYPBCL&C FORE CF TRE INFUT/CUTELT ree my 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 6 of 18) 
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STMT LEV NT 
/* CEFINE ALTCPWATIC STORAGE AREAS (DSA) ey 
91 1 0 DCL TID CrAR(5); #* TERMINAL ID FUR CALLS TO PPL 4¢ 
92 1 0 DCL (PTRLPAPL»PTRLERRPAF) PTR; 7* PCINTERS FGR PAP AREAS 4/ 
93 1 0 DOCL 1 MAML_AREAS ALIGHKEC, 7* MMU CCNTRCL AREAS */ 
3 MPL_DUMMY FIXEC EIN( 31}, 
3 MCB CrAR(4E), 
3 MCry 
5 MCWl CHAR()), 
5 MChz CRHARI1) 5 
5 MCnt CHAR(1), 
5 MCw4 CraAR(1)3 
G4 1 #0 vCL 1 FHLAREAS ALIUGNEC, /* FILE FARDLER CCATROL AREAS *8/ 
3 FRHUODUMMY FIXEC BIb(21)5 
3 EXTDSCT CrAK(4EDs 
3 FrCWy 
5 FrCal CraARtl), 
5 FrCa2 Chak lids 
& FrCn2? CrAR(1)5 
5 FrCa4 CrAR(1); 
95 1 #0O DCL 1 PAKT_RECURL» /* 1CC SYTE ELAM RELCCKC wITHClT KEYS 8/ 
3 PLRKEC_PAhT_DETE#, 4* PART INFGUace e/ 
5 PLREC_LPIN FIC'(5)S', /* eee ThE KUMEER / 
5 PLREC_LDES ChAn(ba)y 4* eee THE CeSCRIPT. */ 
5 PLRECLUNT CRAR(S), /* eee TRE ORGER UNIT #/ 
3 PLRECLPRC FIXEC CECIMAL(754)5 ¢4* PRICE CF A UNIT a/ 
3 PLREC_LMFRK_NLP CRAR (15), 49 MANCFACT. NUPEER *#/ 
3 PLRELCLFILLEK CrAR(17); 7m Fit TE 1CC cY¥TES */ 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 7 of 18) 
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STMT LEV AT 


DCL 1 STOCK KECORD, 7* 80 BYTE WSA4M RECORE */ 


3 DELETE_CRAR CrAR(1), ye */ 
3 S_REC_KEY_FIELLs /® TRE KEY TO FILEves. */ 
5 S_REC_WHS PI1C'(2)S", /* ose WAREFCUSE NLM® 97 
5 S_RECLPNC PIC*(5)S%, /4 ees PART NUMBER / 
3 SLRECLFILLER CrAR(2B)5 /9 a/ 
3 S_REC_STLECK CATA, 7* STCCK DATA FORK os. */ 


5 SLRECLALC CraRi2idy 7* wAREFOUSE LOCATICN #/ 
5 SLRECLLEV FIXEL DECIPALI7)» 
7* AMCUNT IN STCCKaee */ 


5 SLReEC_LET CrAR(E), 7*® eae AT DATE os 
5 SLRECLCRO FIXEL CECIPAL(7)5 
7* OQRCER NEECS aac / 
5 SLREC_COT ChaARte€); J* eee AS GF DATE a/ 
S7 1 0 OCL 1 UATE, /* CATE EDITING ¥/ 
3 MONTH CrAK(2)5 7* TC FOLG TRE PCANTr #/ 
3 SLaSkl Crakk lds /? SLASr a/ 
3 DAY CrAk(2)e¢ 7* TC FOLG TRE CAY 2/ 
3 SLASKZ CrAR(1}5 /* SLASH a/ 
3 YEAR CrAkt2)3 7* TO FOLD TRE YEAR v/s 
Sb 1 0 DOLL CURRENT_LFILE Crake); 
7* CONTAINS FILE NAME TC BE ACCESSEL #/ 
95 1 ¢ DCL P&RKT_LRECURD_PTK FT; 7* FTIR TO FLAT RECCRE SITKLCTURE 
FOR CALL TO SCPile */ 
icc 1 6 DCL «kENWORD FIXED pIN(21);3 7* FIELC FUR RBA CONVERSICA as 
1C1 1 0 DCL KEY_LFIELL Crar(6);3 7* wILk CURTAIN VSSP KEY ¥/ 
We 1 #0 DCL MAP_LGREUP_A CrAR(E); 7* wILk CONTAIN MAFGKCLP NAPE PY 
103 1 0 CCL PARLEL CHAK(E); 7s wILhL CURTAIN PAP NEPE 8/ 


ERROK_MAP_A CRAR(E)} 73 wILb CUATAIW EKKOE FAP NEPE 87 


ERROK_LFLAC FIXED CeClracidd) INIT(C); 7* ERRCR Fite es 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 8 of 18) 
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STMT LEV AT 


/* THE PAINLINE RCLTINE - LEVEL ONE GCF SCPLIA 


1 #0 MAINLINE: OG; 
107 1 #1 RC = 0; /* INIT TRE INTERCOMM RETLRN CCLE 9/ 
108 1 1 TIC = MSGHTIC; 7* SAVE TERPINAL=ID FCR MMU CALLS *#/ 
109 1 1 STRING(MCR) © ° "5 /* INIT MAP COANTRCL WCRO 9/ 
110 1 1 MAP_GRCUP_A = IC_MAPGRCLP; /* YN1T MAP GRCUP NARE a/ 
111 1 1 MAP_LA = IU_PAP; /* INIT MAP NAPE o/ 
1 1 ERROR_MAP_A = ERRGR_PAP; 7* INIT ERRCR MAP N2&PE o/ 


7* NCh CALL PAFIN TC MAP THE INPLT MESSACE 


CALL MAPIN(IMCByMAP_GRCOLP_AgPAP_AyIN_MSG_PTR9MCh)} 


1l4 11 PTR_MAPL = IN_MSG_PTR3 7* PeSS2GE PTR FAS CHANCED #/ 
11s 11 PTRLERRMGP = PTR PAPI; s* ERRPAF WILL CVERLAY I/C REP #/ 
7 INPLT PESSAGE TC BE MAPPED - CHECK RESULT 9/ 
lle 1 1 UNSPEC(VERB) = ° "5; /™ NC VERGE IN TRE CUTPLT PESSACE #7 
11?) 1 1 IF UASPEC(PARTACT) a= ''y $ UNSPECEURRSNOT) as 'fE 
TREN /*® INWALIO INFLT @ 97 
DG; 
ll6 1 2 ERKOR_FLAG = 1; 
119) ls 2 LEAVE PAIALINE; 
120 1 2 ENL3 
w2l610 1 ELSE 


TF MCnl ae 'CP 
THEN J? MAPIN ERKCK ¥/ 
DG; 


122 1 2 cERRCK_FLAG © Z} 

123 1 2 LEAVE PEINLINE; 

124 1 2 END 

125 1 1 STRING(MCH) = ! A’; 7* CLEAR FLAG/ATTRIBLTe& cYTES e/ 


7? PAKE CALL TO MLPCLk ty 


CMLL MAPCLRIMC hy MAP_CRCLF_AgPAP_AgPAPLyTILDG 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 9 of 18) 
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STMT LEV NT 


/* NOW LETS READ THE PART RECCRCE FILE (BCAP) LSING INPLT PART AC 


PART_KECORD_PIR = ACCRIPART _RECURD); /* INIT REC PTR 
RoNWORD © RBNBYTE; /* CCAVERT JAFLT DIGIT TC BINARY 


/* MAKE CALL TO SCPL1E@ TO OBTAIN PART RECCROE 
CALL SQPLIB(PART_RECCKC_PYR»RENRORD RCI; /* CET PART REC 


ERROR_FLAG = KC; /* SET ERROR_FLEG 
RC © 03 /* RESET I1COP RETLRA 
TF STRINGUPLRECL FIN) a= STRIAG(PAKTNCG) 

7* KECCRD PART# GIVER PAKT2 
TREN EKRLRLFLAG = £35 7* NG» PART NO ACT FCUARL 


IF ERROK_LFLAC as ¢ y* ECAP RCUTINE FAIL (SCPLIE)? 
TREN LEAVE MAIALINE; 7* YES, LEAVE TRE MAIN LIKE 


/* ALL IS Uk SU FAK = SC LETS PCVE PORT REC CATA TU ULTPLT AREA 
PRIDETA = P_REC_CES} /* PAKT DESCRIPTION TC I/C PAP 
CRDUNT = P_REC_UNT; /* UNITS TC 1/C PeP 
PRTPRC = P_REC_PRC; /™ PERT PRICE TC I/L PAF 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 10 of 18) 
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STMT LEV AT 


/* ALL IS GK SU FAR = SO LETS GC ANC CETAIN A STGCK RECGRD BY 
/* READING ThE STOCK FILE (VSAP) USING TRE WARERKGUSE IN THE KEY a/ 


CALL VSAM_READ; /* CALL PROCECURE TC 0G REGLEST 


IF ERROR_FLAG am 3 /* IF FILE SELECTEDs RELEASE IT es 


THEN 
DU; 
135 1 2 STRING(FFChH) = ! 5 
/* IN]T FrCw FCR CALL TO KELEASE ¥*/ 
7*® ACh PAKE CALL TO RELESSE 9/ 
140 1 2 CALL RELEASECEXTCSCTsFrCn) 3 
/* ALwAYS RELEASE TrE FILE */ 
141 1 2 END} 
142 11 IF ERROK_FLAG as ¢ 79 VSEM READ ROLTINE Fede 7? #/ 
TREN LEAVE MAINLINE; 7* YES, CLEAVE TRE MAIN LIKE 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 11 of 18) 
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STPT LEV AT 


Figure 48. 


Sample Processing Programs 


/* ALL FILE J3/C 1S CUMPLETE>s SENC AN CUTPUT MESSACE 
STRING(MCw) & ° 5 7* IN] T MAP CONTROL WCRD 
/* NOW PAKE CALL TC MAPCLT 
CALL MAPOUT(MCByMAP_CRCLF_AsPAP_AsPAPloPCwyoTIL)§ 
IF MCwl ae O° /* MAPOLT FAlL 2 
THEN /* YES 
OU; 


ERROK_FLAG = 23 7s ICCP WILL SEND ERROR RESPONSE 
LEAVE MAINLINE; 


END; 
/> abe OK IN MAFCLT = LSE PAPEND TG C PSE VIA FESENG 
STRING(MCH) = * C 5 7@ SET LF C UPTICK FGR MAPEND 


7* ACw PAKE CALL TO MAPERNY 


CALL MAPEND(PCEyYAPI yPFCw) | 
/> CUPFY SECOND PARAMETER 


lf MCh) a= %6! 7* MAPEND FAIL 2 
THEN ye YES 
DO; 
ERROK_FLAG = 23 


7* CELL MEFFURGE = CANCEL CLTFUT MAPPIAC 
CALL MAPLRAGEIPCE); 
LE&VE MEINLINES 
ENC; 


ENO MAINLINE; 


Sample PL/1 Subsystem SQPLI1A (Page 12 of 18) 
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STMT LEY AT 


/* CONTROL COMES HERE AFTER EXECUTICN GF TRE MAIN LINE RCUTINE t- 
/* CHECK ITF ERRGR_LFLAG HAS BEEN SET ANC IF SG SEND APPROPRIATE 
/* EKRCR RESPONSE 


IF ERRGR_FLAG az C 
TREN 
DO; 


STRING(MCh) = * an 
/* CLEAK 1/C MAP FOR ERRCR MAP 


/* NCw MAKE CALL TO PAPCLK 


15S 1 o1 CALL MAPCLRUFChyMAP_GROLF_fSoMAP_AsMAPI,TICIS 

1eéC 1 1 ENC; 

161 1 0 SELECT (EKROR_FLAG); 

162 1 ol WhRER (0)35 4* CkKy NC ECTICKA 47 

163 lol WHEN (1) 7* INVALIC INPUT */ 
cc; 

164 1 2 ERRMSG = "INWALIC CéTo: PARTAC € weSAC MUST GE ALMERIC'S 

165 1 2 CALE SEACLERKRIPSC; /* SEL TRE ERREK MESSACE */ 

166 1 2 END; 

167 loi WHEN (2} J» MPL FAILOR:e 8/ 
CC; 

les& 1 2 RC = 123 /* INTEKCCRR SENCS AK ERRUR PESSFCE?S/ 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 13 of 18) 
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STPT LEV NT 


170 


WHEN (3) 
DO; 


fe eC CO as 


ERRMSG = "AC COCARD FOR FILE SELECTED’; 
CALL SEACLERR PSG; 7* SEND TRE ERKOR PMESSACE *#/ 


ENC; 


WHEN (4) 


/* TO ERRCR #7 
00; 


2 ERRMSG = "I1/G ERRCR CURING FILE ACCESS, TRY ACAIN'; 
2 CALL SERCLERR_P#SC; 7® SEKCD THE ERRCR MESSACE 9/ 


ENC; 


WHEN (5) 
UC; 

175 1 2 ERRMSG =» *RECCRE ACT FCUNCSS 

180 1 2 CALL SEAD_LERR PSC; 7* Sen THE ERRCR MESSSCE P/ 


7* RECORD ACT FCURC 


1@1 1 2 END; 


162 2 1 wrEN (6) 7s KECCKE NCT FOUNC IK wAREFCUSE 87 
LCs 
163 1 2 ERRMSG # "PART NUMBER ACT FLUND IN wAREFOUSE'; 


164 1 2 CALL SENDLERR_ FSC; 7* SehNC TRE ERRCR MESSACE 9/ 


1é5 1 2 ENC; 
186 11 ENC; 7* ERL ERRGR FLAG CHECKIAG */ 
7) FREE THE PAPPING ARES 87 
187 1 ¢ STRING(RCn) = ° a) 
186 1 0 CaLL PAPFREE (CR CmyhAP_CROLE_byPAP_byPhTRK MAP) 5710); 
Re TuRn; ye cEbve SCPLIA = ALL OCKE 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 14 of 18) 
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VSAM_READ? 


Figure 48. 


Sample Processing Programs 


/* PROCEDURE TC READ TEE VSAP FILE -— DDNAME®STOKFILE 
PROC; /* READ VSAP FILE BY KEY #/ 


SLRECLWHS = wWrSNC; /* wHSNC IS PART CF THE KEY 
STRINGESLRECLPNU) © STRING(PARTAC); 
7* PARTAC IS PAKT CF THE KEY 
KEY_FIELD = STRINGCS REC KEY FIELC); /* TRE VSAPR KEY 
CURRENT_FILE = DOLSTCCK; /* SET FILE TO BE ACCESSEC 
STRINGCFHCh) = ° "5; /* INIT FILE FANULER CONTROL BCRE 
UNSPECCEXTCSCT) = ''B; 
/* IAJT FILE FARDLEx CCNTRCL ELOCK 


CALL SELECTCEXTUSCTsFRCwyCURRENT_FILEI; /* SELECT FILE 
IF FeCwl = 'S! 7* SELECT ERRCR ?, AC COC 
TREN 

DO; 


ERKOR_FL«éG = 3; 7* YES - SET BAC RETURN CCLE 
RETURN; 


ENC; 


STRINGLIFHCA) @ ! ar 7* SELECT UKs INIT FRCw FOR KEEC 8S 


CALL GCETVCEXTUSCTyFRECmySTCCK RECCRCgKEY_FIELC)3 
7* VSAP KEAC BY KEY »/ 


SELECT (FrHCwl); 7* SELECT CETY RETURN CLCE */ 


wrEN('1"} /* 1/0 ERKCR ¥/ 
UC; 


ExRGR_FLAG = 4; 
keTuRh; 


ENO) 
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209 
210 
211 
212 
213 
214 
215 
216 


217 


Figure 48. 


Sample Processing Programs 


WHEN (92°) /*® RECORD ACT FCURE 


0; 


ERROR_FLAG = €3 /* 
RETURN; 


wAKEBCUSE MATCR NOT ECUAL 


ERO 
WHEN (°°) 
OC; 


/* INVALID FUNCTICA 


ERROR_FLAG = 4; id 
RETURN; 


TREAT AS 1/0 ERRCkK 


ERD; 


WHEN (°CO') 
CO; 


/# SUCCESSFUL ACCESS 


/* CoTAIN INFORPMATICN FRCP TRE STOCK RECORG JUST REACT 


wWHSLCEC # 
STKLEY ® 
MONTH = 


S_KEC_ WLC; 7* MUVe TRE LOCATICK 
SLREC_LEv; 7* MCVE STCCK LEVEL 
SLBSTR(ICSLREC_LL IT) 9l92)3 
/* EXTRACT TRE 
SURBSTRECSL REC LO Ti y29e)3 
7* EXTRACT TFrE 
@ SLESTRCCS_KECLLO1T)59592)3 
/* EXTRACT TRE YEAR 
"75 4* PCOVE IK TRE 's'S 
STRIAC(LATEDS /* POVE LEVEL LATE 
SLREC_LORL; 7* MCVE GRDERK LEVEL 
SLBESTRCCS REC CLT) 9492)3 
/* EXTéCT TRE FCRTE 
SUBSTR CCS Re CLOL Ts eye)3 
/* EXTRACT TRE CAY AC 
SLESTRCCIS RECLCOUT) 592); 
7* EXTKACT TRE YEAR 
7a nCTE */*S TR ALKESLY 
STRIACIUATED 7* MCVE STCCK LATE 


FCATE 
DAY & 


DAY KC 
YEAR 
SLASK]»y SLASH2 = 
LEVUATE = 
STKGRC = 
MCNTE = 
ChY = 


YrAk «& 


OKCDLTE = 
ERu; 


Encl; /* 


ENG CF Stic 


END VSAF_READ; 
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STMT LEV NT 


/* PRCCECLRE TC SEND AN ERROR MESSACE 


SEND_EKR_MSG: PROC; 


STRING(MCnr) = ! /* INIT MAP CONTRCL WCRC 
LNSPEC( MCh) © 8B; 7* CLEAR PAP CONTROL #BLLCK 


7® NCw PAKE CALL 10 PAPCUT 


CALL MAPOUTCPCBsMAP_CKCLP_AyERRCR_PAP_A,EKRMAP gMCwyTIC0) 3 
/* WAP THE ERRCR MESSACE 


TF MCal = ‘O° 7* SLCCESSFUL MAPCLT 7? 


TREN /@ YES 
Du; 


STRING(MCW) = * Cf; 7* & CPTIOA FER MAPERY 
MCn3 = WRITEL; 7* NCT ERASE@nRITE 


7* NCw PAKE CALL TC MAPENC 


CALL PAPENUCMCE sPAPl PCW )3 
7* SEAC TRE FAPPED MESSACE 


IF MCwl am PEF /> FPESS#CE QLELED Ck ? 
THEN ye AL 
uO; 


7* ACw PsKe CALL TO MAPLRCE 
CALL MAPLAKCE(MCc); 
/* FUKGE MML wCRK ARES 
= 12; 
/@ INTEKCCPM SERCS AN ERRCK MESSACE 


J* MEPCUT FaILeEubs IC SENOS A KPESS£CE 
END; 


ENC SEALLERR_FSG; 


ENC SUPLiLa; 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 17 of 18) 
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STORAGE REQUIREPENTS 


BLOCK, SECTION OR STATEMENT TYPE LEKGTH CSA S1ZE 


*SCPLIAL PROGRAP CSECT 21S¢ 
*SCPL1A2 STATIC CSECT 7Ceé 
SCPLIaA PROCEDUKE BLOCK 1¢4C 
VS A4M_KEAD PROCEDLKE BLCCK 55e 
SEAG_ERR_?SG PROCEDLRE BLOCK 3eC 


Figure 48. Sample PL/1 Subsystem SQPLIA (Page 18 of 18) 


125.4 


Chapter 10 


STMT LEV NT 


Sample Processing Programs 


/* PROCEOURE SGPL1s TO READ A BOAM FILE AND RETURN TRE RECORD 


SQPL1IB: PROC (PART_RECORC_LPTR»FBNKORC RC) 
OPTIUNS(REENTRANT);5 
7* DEFINE TRE INCUPING PAKAMETERS 
OCL PART_RECURD_PTK PTR3/* INPUT PARM 1 = PTR TC REC'D AREA 
DCL (RoNnORDs /* INPUT PARR 2 = PART AKUMBER KEY 
RC) FIXEC BINC31)5 ¢* INPUT PARP 3 - RETURN CCOE 


DCL 1 FILELNAMES STATIC, s/* FCK CALLS TG THE FILE FANCLER 
3 OC_STCCK CHARLE) INIT(*STCKFILE')» NCT USEO HERE 
3 DDO_PART CnAR(E) INIT(*PARTFILE'D3 
7* DEFINE AREAS FCR LSE BY ThE FILE FANDLER 
OCL 1 FHLAKEAS ALIGNEL, /* FILE FANDLER CONTROL AREAS 
FHLOUMMY FIXEC BIN(31)» 
EXTOSCT CRAR(4EDs 


FrChy 


FrCnl CrAR(1)5 
FrCn2 CnHAR(1),5 


5 
5 
5 FnCad CrAR(1L)s 
5 FrCw4 ChAK(1)5 


PAKTLRECURC paASECIPARTLRECCRU_LPTK) 5 
/* (CC EYTE BLAM RECORC wITFCUT KEYS »/ 


P_REC_PART_DATA CFAR(1CC);} /* SUE DEFINITICN NOT 
KEGLIREO RERE. THE SUB 
LEFINITIUNS ARE FCK 
UCCUKENTATICN PURPCSES 
LMLY.« 


P_wEC_PART_DATAy PART INFGees 


5 PLREC_PIN P1C'(D)G', wee THE KUMEER 
5 P_LREC_DES CnAR(D4)5 eae THE DESCRIPT. 
5 P_REC_UAT CRAK(E)s wes ThE ORDER UNIT 


P_REC_PRC FIXEC GECIMAL(7594)5 PRICE OF A UNIT 
P_REC_LMFRLNUM CFAR(15)5 MANLFACT. NUPBER 
P_RECLFILLER CRAK(17) SEMI CCLCN FILL TO 100 BYTES */ 


Figure 49. Sample PL/1 Subroutine SQPLIB (Page 1 of 4) 


126 


Chapter 10 Sample Processing Programs 


STMT LEV AT 


/* INCLUDE PLIENTRY = DEFINES ICCM ENTRY PCINTS = AS ASM INTER ¥*/ 


ZINCLUDE PLIENTRY 3 99 eee ee eee hee REE EH HHO ERE HEEHE SHEESH ERE EEE E HDD 
1 © DECLARE (¢ SELECT, 
RELEASE, 
READ, 
WRITE, 
GET, 
PUTs 
GETV, 
PUTV, 
RELEX, 
FEOV, 
COBPUT, 
*SGCCCLs 
FESEND, 
FESENLC, 
CCBSTURF, 
CONVERSE, 
LUGPUT, 
CKINT, 
PAGEs 
CoUILC, 
QUPEN,s 
QkEAD, 
QKEADX, 
OwRITEs 
CrRITEX, 
QCLUSE, 
FECMDDC, 
FECMFDENK, 
FECMRLS&ty 
MAPIN, 
PLPCUT,s 
MAPFREE, 
MAPENLC y 
MAPURLE, 
PAPCL Ey 
DnwSSNAPs /7* REL 1¢ 
INTSORTCs 7* REL 1C 
INTSTGORe» 
INTFETCHy 
INTUNSTO) ENTRY OFTITNS (&SP INTER); 
FERRETS Pe ee /* FOR CiRECT CALLS TC ILOh AND USER RLUTINES 


DCL CURRENT_LFILE CHAK (ED; 
7* CONTAINS File NAME TC BE ACCESSEL 
OCL KB CrAkK(3)5 /* 2 EYTE KBN FOR BOAM REAL 


Figure 49. Sample PL/1 Subroutine SQPL1B (Page 2 of 4) 
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STMT LEV NT 


/* EXECUTICN CODE 


RC = G3 /* INIT THE RETURN COCE 
UNSPEC(KBN) = SUBSTR(LNSPEC (RBNWORC) 95524)3 
/* SET RBN UP FOR READ = MLST BE 3 BYTES 
CURRENT_FILE © DD_PaART; /* SET FILE TO BE ACCESSED 
STRING(FHCW) = & *} /* INIT FILE FANDLER CONTROL WCRD 
UNSPEC(EXTOSCT) = *'p; 
/* INIT FILE FAKOLER CONTROL BLOCK 


CALL SELECTCEATUSCTsFrCWsCURRENT_FILE)$ /¢* SELECT FILE 
IF FHCwl » *9! 7* SELECT EKROR 75 NO CC 
TREN 

DU; 


kC = 3; 7* YES - SET BAC RETLRA COCE 
RETURN; /* EXIT PROGRAM 


END; 


STRING(FHCW) = ¢ an /* SELECT LK» INIT FRCW FOR KEADS/ 


CALL READ EXTUSCTsFrCh sPART_RECORLC skBN)5 
7* BUAM READ BY KBR 9/ 


Figure 49. Sample PL/1 Subroutine SQPLIB (Page 3 of 4) 
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START LEW AT 

22 2 0 SELECT(FHCW1); /* ChECK READ RETURN CODE */ 

23 1 #1 WHEN('O'); /* OKs DO NOTHIAC */ 

24 2 31 WHEN(*2") /* 1/0 ERRCR #/ 
DO; 

25 1 2 RC ® 43 

26 1 2 END; 

27 1 #1 WHEN('2*) 7*® RECORD ACT FCUARD 9/ 
DO; 

26 1 2 RC 8 5; 

29 1 2 END; 

30 1 #1 WHEN('9") 7*® TAWVALID FUNCTICKA 9/ 
0G; 

31 1 2 KC = 4; 7* TREAT AS 1/0 ERKCR #/ 

32 1 2 END; 

33 1 #1 OTRHEKAISE; 

34 141 END; i” END FRCwW1 CFECKING s/ 

35 1 0 STRING(FHCA) = ' 5 7* IKIT FrCw FOR RELEASE #/ 

3¢ 1 #0 CALL RELEASECEXTOSCIsFRCH)S 7* RELEASE THE FILE */ 

37 1 0 END SOPL16; ‘* Trad s Ace FOLKS a/ 


STORAGE REQUIKEMENTS 


BLOCKs SECTION OR STATEMENT TYPE LENGTH DSA SIZE 


*SOPL1B1 PROGRAM CSECT 5065 
@SCPL1IB2 STATIC CSECT 124 


SOPL1B PROCEDURE BLOCK 506 


Figure 49. Sample PL/1 Subroutine SQPLIB (Page 4 of 4) 
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SUBSYSTEM TESTING 


11.1 INTRODUCTION 


After a new subsystem has been thoroughly desk-checked and 
compiles cleanly, it becomes necessary to test the subsystem's 
execution under the control of Intercomm. Three methods of testing are 
available: 


e Simulated--batch execution of Intercomm with a simulated BTAM 
Front End. Message input streams are created via the 
CREATSIM utility program. Additionally, 3270 terminal input 
and output screen, or output printer, images are formatted if 
the SIM3270 utility is implemented for the simulation mode 
execution. Illustration of this mode of testing is provided 
in this Chapter, and is particularly useful for testing 
messages processed via the Message Mapping Utilities. 


e Test Mode--batch execution of a Back End Intercomm with 
message input from a card-image data set, as described in 
Chapter 12. 


e On-line Testing--an on-line system is necessary for final 
testing of all error conditions, multithread processing, etc. 
and can be either a single region system, or a satellite 
region used primarily for testing within a Multiregion 
production system. 


11.2 DEBUGGING APPLICATION PROGRAM PROBLEMS 


Text and descriptions of error messages issued by Intercomm as a 
result of invalid program logic paths, along with descriptions of 
general debugging techniques for accompanying snaps and abends are 
available in Message and Codes. Additional debugging facilities such 
as dispatcher trace reports, thread dumps and indicative dumps are 


described in the Operating Reference Manual. 
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11.3 TESTING A SUBSYSTEM WITH THE FRONT END SIMULATOR 


As described in the Operating Reference Manual, a test execution 
with a simulated Front End is very useful to determine Front End 
message interface problems that may be harder to debug when using an 
on-line test system. Although the simulation is of certain BTAM 
devices, including a local 3270, the access method interfaces required 
for a remote 3270 or a TCAM or VTAM Front End are essentially 
transparent to the application programmer as the interface dependent 
code is handled by Intercomn. 


This chapter illustrates testing of the subsystem and subroutine 
described in Chapter 10 using the BTAM simulator for 3270 CRT messages 
processed via maps defined for the Message Mapping Utilities. 


To test an application system in a simulated Intercomm 
environment, do the following: 


NOTE: Steps preceded by an asterisk (*) may often be performed 
for the application programmer by an installation’s 
Intercomm System Manager. Appendix C summarizes the 
Intercomm Table entries. 


1. Compile and linkedit the user subsystem(s) and subroutine(s), 
if any. Appendix A describes Intercomm-supplied PL/1 JCL 
procedures. 


*2. Create or add to a USRSCTS member on a user test library to 
contain a Subsystem Control Table Entry (SYCTTBL macro) which 
describes the subsystem. Reassemble and link INTSCT which 
copies the USRSCTS member from the test library (see Figure 
50). 


*3, Define input message verbs in the copy member USRBTVRB via 
BIVERB macros and reassemble and link the Front End Verb 
Table BIVRBTB (see Figure 50). 


*4, Code a SUBMODS macro addition to the COPY member USRSUBS to 
define the PL/1 subroutine and reassemble and linkedit 
REENTSBS which copies USRSUBS (see Figure 50). Also 
reassemble INTLOAD to copy the same USRSUBS if the program is 
loadable, uses direct calls, and is linked with INTLOAD. 


5. Assemble and linkedit MMU maps (Map Group STKSTAT--see Figure 
51) to the MMU load module Library. Load maps to the 
appropriate Store/Fetch data set. Create the symbolic map 
copy member(s) to be included in the program and place them 
on SYMPL1 (PL/1 Vl) or on the library with the program (PL/1 


V2). See Message Mapping Utilities. 


6. Prepare input test message data set(s) using the CREATSIM 
utility as illustrated in Figure 52. The first message 
generates, via the MMU command MMUC, the screen template to 
be used for entering an inquiry transaction. All subsequent 
input messages are for testing the PL/1 subsystem and 
subroutine, including input error conditions handled by the 
application program. 
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*7. 


*8, 


*9, 


10. 


ll. 


*12. 


13, 


Subsystem Testing 


Add control cards to the linkedit deck for the user programs, 
unless the routines are dynamically loadable (see Figure 53). 


Add INCLUDE statements for the simulator (BTAMSIM) and 3270 
display formatter (SIM3270) to an Intercomm linkedit deck 
which was created for the BTAM Front End (see Figure 53). 


Linkedit to create a new Intercomm load module (see Figure 
53). 


Add DD statements to the Intercomm execution JCL for the 
printed SIM3270 output and the input message data set(s) (see 
Figure 53). 


Create test data sets and add DD statements for them to the 
execution JCL (see Figure 53). Note that if a VSAM data set 
is used with a user catalog, place the STEPCAT DD statement 
after the //PMISTOP DD statement (see Figure 53); do not use 
a JOBCAT DD statement. STEPCAT should be omitted if using 
ICF catalogs. 


Execute in simulation mode: 


a. Single-thread test all subsystems; to test a reentrant 
subsystem, specify MNCL=l1 in the subsystem’s SYCTTBL 
macro. 


b. Multithread test reentrant subsystems (change MNCL) using 
several test message input data sets or use a single data 
set as input from more than one terminal. 


The parameter ‘STARTUP’ must be coded on the Intercomm EXEC 
statement. Figure 53 illustrates a sample execution deck 
with test message input (DD statement TEST1) for the sample 
inquiry program and JCL to print the system log. 


The resulting SIM3270 printouts for the simulated execution 
of the sample inquiry subsystem are illustrated in Figure 


54. Note that the underlined positions on each screen 
display indicate attribute byte positions; codes are 
described under the display. On an actual terminal, the 
attribute byte position appears as a blank to the terminal 
operator. See Message Mapping Utilities and IBM 


documentation on programming for the 3270 CRT for further 
information on attribute codes. 


The Intercomm Log printed after the simulated execution of 
the sample inquiry subsystem is shown in Figure 55. 


Test the subsystem concurrently with other application 
subsystems. 
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// TABLES 
//* 
//* DEFINE SYCTTBL FOR SUBSYTEM 
//* 
//STEPL EXEC LIBELINK,Q=TEST , NAME=INTSCT, LMOD=INTSCT 
//LIB.SYSIN DD * 
./ ADD NAME=USRSCTS 
_/ NUMBER NEW1=100, INCR=100 
USRSCTS DS OH 
PQ SYCTTBL SUBH=P , SUBC=Q, SBSP=SQPL1A, LANG=RPL1 , OVLY=0, 
NUMCL=10 , MNCL=2 , TCTV=60 , SPAC=4096 
/* 
//ASM.SYSIN DD DSN=INT.SYMREL(INTSCT) , DISP=SHR 
//* 
//* DEFINE BTVERB FOR SUBSYSTEM 
//* 
//STEP2 EXEC LIBELINK,Q=TEST , NAME=BTVRBTB, LMOD=BTVRBTB 
//LIB.SYSIN DD * 
./ ADD NAME=USRBTVRB 
./ NUMBER NEW1=100 , INCR=100 
USRBTVRB DS OH 
BIVERB VERB=TPL1, SSCH=P, SSC=Q, CONV=18000 
/* 
//ASM.SYSIN DD DSN=INT . SYMREL(BTVRBTB) , DISP=SHR 
//* 
//* DEFINE SUBMODS FOR SUBROUTINE 
//* 
//STEP3 EXEC LIBELINK,Q=TEST , NAME=REENTSBS , LMOD=REENTSBS 
//LIB.SYSIN DD * 
./ ADD NAME=USRSUBS 
./ NUMBER NEW1=100, INCR=100 
USRSUBS DS OH 
SUBMODS LNAME=SQPL1B, TYPE=PL1 , DELTIME=30 


/* 

//ASM.SYSIN DD DSN=INT.SYMREL(REENTSBS) , DISP=SHR 

//* 

//STEPS EXEC ASMPCL,Q=TEST,NAME=INTLOAD , LMOD=INTLOAD 
//ASM.SYSIN DD DSN=INT.SYMRELCINTLOAD) , DISP=SHR 

// 


Figure 50. Table Updates to Implement Simulation Mode Testing 
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STKSTAT MAPGROUP MODE#=1/0,DEVICE=1BM3270 oocoocelc 
MAP1 MAP = - SY ZE=(20,80),START#=(151) 000000zc 
VERB FIELD RELPOS=VERB 0000003C 
FIELD RELPOS=(1ly7),INITIAL® "ENTER TRARSACTION CCOE'sATTRIB=PSN COCO004C 
FIELD RELPOS=(3923)sINITIAL="ENTER DATA sATIRIB=PSN _ €0000050 
FIELD RELPOS=(5y7),INITIAL= "PART NO? *yATIRIB=PARSEL ' ooooccec 
PARTNC SEGMENT 000000€5 
FILLER FIELD RELPOS=(5516) sFORMAT#=(499Z0),5ATTRIB*UNN 00000070 
RBNBYTE FIELD RELPOS=(5520) sFORMAT=( 19920) coco007s5 
SEGMENT 00CC0G77 
FIELD RELPOS=(5522) »FORMAT=1 ,ATTRIB=|PSA oo00ccec 
FIELD RELPOS=(697),INITIAL= "WHS AC2*SATTRIB@=PARSEL 0000009¢ 
FIELD RELPOS=(6)15) sFORMAT#=(3992Z0),ATTRIBSUNN co00010c 
FIELD RELPUS=(64,19) sFORMAT=1,ATTRIB=PSH coccoilo 
FIELD RELPOS=(8523),INITIAL=*STOCK STATLS2*yATTRIB=PSN 00000120 
FIELD RELPOS#(1097),INITIAL="CESCRIPTICA: "sATTRIB@PSA ©000013C 
PRIDATA FIELD RELPOS#=(10)20),FORMAT=54,ATTRIBSUAN c0c00140 
FIELD RELPOS=(10576) sFORMAT=1,ATTRIB=|PSA 00000150 
FIELD RELPOS#=(11y)7),INITIAL= "ORDER UNITS2*,ATTRIB=PSH ooccciec 
CROUNT FIELD RELPOS=(11520)+FORMAT=5,ATTRIB=UAN 0000017C 
FIELD RELPOS=(11526))FORMAT=1 9ATTRIB=PSA 0000018C 
FIELD RELPOS#=(11s40)sINITIAL= "PRICES" ATTRIB=PSA €0cC00190 
PRTIPRC FIELD RELPOS#=(11947) sFORMAT@=(9545$PDS4) pATTRIBSUAN 00000200 
FIELD RELPUS=(11957),FORMAT=1,ATTRIB=PSHK 0000021C 
FIELD RELPOS=(13,23),INITIAL="STCCK STATLS AT WARERKCUSES"y x0000022¢ 
ATTRIB=PSN 00000230 
FIELD RELPOS=(1557),INITIJAL= "LOCATION? *sATTRIB=PSK oocoo24c 
WHSLOC FIELD RELPOS=(15917)sFORMAT#23,ATTRIBSUAN 0000025¢ 
FIELD RELPOS=(15)41))FORMAT=1,ATTRIB=PSK 0000026C 
FIELD RELPOS#(1l6y,7),INITIAL= "ON HAND? *gATTRIB@PSA oocooz7¢ 
STKLEV FIELD RELPOS=(165916)9FORMAT=(7949PD) 9ATTRIBSUAN cocccz8o 
FIELD RELPOS=(16524)yFORMAT=1,ATTRIB®PSK 0000cz9¢ 
FIELD RELPOS=(16s40)sINITIAL="AS OF2"yATTRIB=PSA 0000030C 
LEVDATE FIELD RELPOS=(16547) sFORMAT=Uy,ATIRIBSUAN 60000310 
FIELD RELPUS=(16556)9FORMAT=1,ATTRIB=PSN cocoo32c 
FIELD RELPOS#(1797),INITIAL®= "ON ORDERS 'pATTRIB=PSN 0000C33C 
STKORD FIELD RELPOS=(17517)yFORMAT=(7949PD) gATIRIBSUAN COC0034C 
FIELD RELPOS=(17)25) 9FORMAT=1 y,ATTRIB=PSK 0000035C 
FIELD RELPOS#=(17s40),INITIAL="AS OF: "sATTRIB=PSA 0000036C 
ORDDATE FIELD RELPOS#(17547)sFORMAT=8,ATIRIB@UAN 0000037¢ 
FIELD RELPOS#=(17,)56)»FORMAT=l1y,ATIRIB=PSA C000038C 
ERRMAP MAP SIZE=(1558C) ySTART#=(1091) 00000390 
FIELD RELPOS|#(1lsl),ATTRIB@=SUPRyINITIAL=X'125B5F° Ocooc4cc 
@9@ ABOVE CLEARS STCCK STATUS INFO. WHER ERROR PESSACE APPEARS #88 0000041¢ 
FIELD RELPOS#(14,33),INITIAL="ERROR PESSAGE? *yATTRIB=PAKSEL 0C000426 
ERRMSG FIELD RELPOS=(15510),FORMAT=50,ATTRIBSUARSEL 0C00043¢ 
FIELD RELPOS=(15s61),FORMAT=1,ATTRIB=PSA C0CO044C 
ENDGROUP CC00045C 

END 0cc00460 | 


Figure 51. MMU Maps Used by Sample Subsystem 


NOTE: the PL/l-oriented parameter BASED is not coded on the MAP macro 


because the default is YES (map mame declared as BASED on 
PTR_mapname). 
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//CREATSIM JOB 0001000¢ 
J/CRS PROC T= . ooo2ococ 
//* SCRATCh OLD TEST INPUT DATA SET (CIF ANY) oo00300CcCc 
4s EXEC PGM=lTEFBR14 0004000C 
//SCR DD DSN@INT.TETsDISP@#(OLD,DELETE) 00050000 
4/9 CREATE NEW TEST INPUT DATA STREAM FOR 327C DEVICE 00cé0000 
7/CRS EXEC PGM=CREATSIM aqoo7ccac 
/J/STEPLIB DD OSA#INT.-MODRELsOISP=SHR 00080000 
J/SYSPRINT DO SYSCLT#A oo0soo0c 
//SYSUT2 DD DSN@INT.TETsDISP=(yCATLGs»CATLG) pUAITSSYSCAy co1oo00o0c 
4/ VOL@®SER#INTOOLsSPACE=(TRKs(lyld) co011000¢€ 
4/* PRINT MESSACES GENERATED ON TEST INPUT CATA SET 0012000¢€ 
//DUMP EXEC PGMSIEBPTPCH 001300CC 
J/SYSPRINT OD SYSOUT#A c914000C 
//SYSUT) DD DSN#*.CRSeSYSUT2;DISPs0LD 0015000¢C 
J/SYSUT2 DD SYSOUT#A cc1é60000 
4/ PEND c0170000 
//* FOR TRIS EXECUTION OF CREATSIM, THE END-OF-CARD CFARACTER 1S A co18000c 
4/4 SEMI*CCLON, (USE ALSO AFTER THE VERS=-FRONT END SEES THE SBA), 0019000C 
//* THE PESSACE END CHARACTER IS AN EXCLAMATICN PCIANT (e080). cG20000C 
//EXECCRS EXEC CRSsT#TESTIL 0021CU00C 
J/CRS.«SYSIN DD *® co220ccc 
GRAPHICy,»ACDy5FF CCONTINUATICN COCE 002300CC 
GRAPHIC,ACC,<7D ENTER KEY co24000C 
SBA »M2 USING MODEL 2 SCREEN SIZE c0250000 
€ MMUCyShChy(STKSTATsMAP1)! oceecoce 
<3 0027000C 
SBA,0102; co28o0oc 
TPLIs cc2so00c 
SBA:s0516; co3cccoo 
123453 00310C0C 
SBA, C615; c032000C 
20c! cC033000C 
q 3 0034CC00 
$6A5,0102;3 0035ccoCc 
TPL; 0036C0CC 
$BA,0516; c0327000C 
55555; 00380000 
$BA,0615;3 C0390CG00 
2001 oo4ccccc 
© oi 0041CC0C 
SBA,0102; 0042000C 
TPLL c043000C 
SBA;0516; C0440000 
12248; 0045CC0C 
SbA,0615; 004e60C0C 
30C! 0047000C 
© 3 co4so00c 
$bA;01C2; c04s50000 
TPLL; cosccooc 
$84505163 005100CC 
12341; 005200CC 
SBA,sC6153 cc53000C 
600! 00540u00 
Figure 52. Input Test Messages Generated via CREATSIM (Page 1 of 2) 
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© 3 0055000C 
SBA»01023 : 0056000C 
TPLI3 €057000C 
$84,05165 co58000C 
423455 0059000C 
SBA,0615;5 0060000C 
200! Ccé10000 
© 5 coé20000 
SBA,0102; 00€30C0C 
TPLI; 0064000C 
SBA,0516;3 coes000c 
12345; C0660000 
SBA,0615; CCé70006 
B00! caesococ 
“© 5 océ90cocc 
S$BA,01023 0070000C 
TPLI; Cc71000C 
$BA,C5163 cc72000Cc 
1234Xx; co73ccoc 
$B4,0615;3 00740CCC 
20Y! 0075000C 
“3 Cc76e000C 
$B4,0102; €c77000C 
TPLI; 0076C000 
5$B4,0516;3 0079000C 
12349; ooso0coc 
SbA,06153 coelooo0c 
100! cce2ococ 
© 3 O0&30C0C 
$B4,01025 O0840CCC 
TPLI; coes000c 
$6A,0516; OCE6000C 
12342; cce7o00c 
SBA,0E15; ccesoo00c 


1c0! ooesoccc 
J/DUMP.SYSIN DD * 00Ss000OdCc 


PRINT TYPORG#®PS ys TUTCONV®XE sCNTRL#=2 €051000C 
4 C0S20C0C 


Figure 52. Input Test Messages Generated via CREATSIM (Page 2 of 2) 
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J/EXECTEST JOB (ICOMTEST es 920) 9'SQPLIA TEST’ oCLASS=Ay 
4/ RESTART@=(GENLINK.ASM) 


//PROCLIB CD OSN@INT.PROCLIByDISP=@SHR (AS NEECEC) 
J [PEO OOHEEEEE EEE RET E EEE REET EER EERE HEH ESE EEEE EEE ERE SEE E EEE EE EEE SEEDED OOS 


//* THE RESTART PARM IN THE JOB STATEMENT RESTARTS TRE TEST AT TEE * 
//* BEGINNING. IF YOU WISH TC RESTART AT A DIFFERENT STEP,» COCE * 
//* RESTART=STEPNAME OR RESTART#STEPNAMEePRCCSTEPNAPE * 
4/* s 
//* NOTE? wHEN USING A VSAM FILEs IT 1S NECESSARY TO EXECLTE IDCAMS * 
//* TO VERIFY TRE FILE IF A PREVIOUS EXECUTION ABENDED. * 
L/PSESSHSESESHH SHEESH HE SH SHEESH SEHE SESE EE SEH EH SEE HEHE SESH SETHE ESESESEH EE ESTES 
//* 


JS FSSSSSESESHEH ESHEETS HEHEHE SESE SSH THE SH ESSE SEEK HEHEHE HERE SEFS ESE SESE RE SS EE 
4/* STEP CENLINK GENERATES A STANDARD STAM FKCAT END LIAKEDIT LECK * 
4/* WIA ASSEMBLY QF THE ICGPLINK MACKCe IF ONLY A VTAM FRCANT END IS * 
//* USED CNeLINEs A SETGLOBE wITh THE BTAM GLCEAL SET TC 1 PLST EE * 
//* IN ThE LIBRARY SPECIFIEL SY TRE O= PARM. 4LC CR CRANGE PaRBS FCR * 
4/* TRE TCOMLINK MACKC BASED CN INTERCOMM FACILITIES USED. * 
//* TRE GENERATED DECK (SIMLINK) IS PLACED UN IATSSYMTEST. * 
7/* BROQTE?® THE SPECIFIED FRONT END NETWORK TABLE (FERETRRK) ThAT IS * 
* 
* 
s 
s 
* 


//* ON MODREL CONTAINS A DEFINITION FOR THE TEST TERMINAL 
//* TESTL AS A LUCAL BTAM 3270 CRT. (COPY TC MCDOTEST) 
4/* STEP RUM NUMBERS GENERATED LINK CECK IN INCREPENTS OF 1006 
//* FUR ADDING INCLUDE STATEPENTS IN GEAINCL STEP. 
Lf EPREHEH EEE EERE THT T SHES ETEK EET EH HEHEHE THEE REESE TEA RE REESE HESS 
7/GENLINK EXEC ASMPCyDECK=DECK G2 TEST 
7/ASMASYSIN DD * 
ICOMLINK MAUBYES  sFETABLE#FENETWRE yPLLBYES 


ERD 
J/SYSPUNCE DD OSN#INTSSYMTEST(SIMLINK) sDISP#SHR 
//* NUMBER CENERATEC LINKECIT DECK 
//NUM EXEC LIbesQ=TEST 


J/LIBSSYSIA DD * 
e/ CHANGE NAME#SIMLINK 
e/ NUMBER NEW1L#1000,INCK=1000 


s4* 

JL/FSSHESH SHOES HSHS RHEE SSE SEEKS SESS SHE TRE STE EHO EO TH AH VOR RH SHH RES HEE 
//* STEPS SCRSCR AND ALLOCSCK DELETE AND RE-ALLCCATE TRE LuAt * 
7/*  MOOLLE LIBRARY USED IN THE TEST CALSG USED FOR CYALL Ie) ‘ 


LfPESSASESSSHHHHSEH HESS ER ES EHS HEH VEE STH EET EH HHP SHER HSH REET HEHE EES AEE 
J/SCRSCR EXEC PCM=IEFBR14 

//FILEL DD DSN#=INT.MUDSCR yGISP=(GLLE DELETE) 

7/ALLUCSCR EXEC PCM#IEFBR14 

J/4 DOC DSN=INT.MUCSCR pUISP#( sCATLG)sUNIT#SYSUAS 

4/ CCB=INTeMQDRELs VOL=SER#INTCUlLSs 

4/ SPACES(TRK5(30557)) 7 RECCROS PER TRK/3280 

4/* 


Figure 53. Linkedit and Execution JCL for Simulation Mode (Page 1 of 3) 
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/ [POR ARSHO ESSERE STRESS EE SESE EE HEDEREEE SOOTHES ESEREEDEEEESED EE EEERESERS 
STEP GENINCL CREATES INCLUDE DECK USED BY THE LINK EDIT STEP? * 
THE ADDED INCLUDE STATEMENTS ARE FOR THE SAPPLE SUBSYSTEM AND * 
SUBROUTINE, AND THE REQUIRED SIMULATION MODE MCCULES. * 
IF THE TESTI TERMINAL IS NOT IN THE SYSTEM PRISTATB TABLE» USES *& 
INCLUDE MODREL(PMISTATB) bd 
INCLUDE MODREL(PHMIDEVTB) * 
INCLUDE MODRELCPMIBROAD) * 
TRE ABOVE ASSUMES THE CONTROL TERMINAL IS ANAMEC CATOL. * 
J POEOOERE ERR KEHE SHES THES EHS HOKE KSEE ESE SEH SESH EH ERT ETE SETTER EE ERTS 
//GENINCL EXEC PGM=TEBUPDTE 
//SYSPRINT DD SYSCUT#A TC PRIAT CRANGES 
//SYSUT1 DD DSN=INT.SYRTESTyDISP#SHR 
J/SYSUTZ2 CC DSNMEEINCL sDISPElyPASS) pUNIT#=SYSDAySPACES( TKK, lOslsll)¢ 
// DOCBe(BLKSIZE*60,LRECL=60) 
JISYSIN DD * 
e/ CHANGE NAME®SIMLINKsLIST#ALL 
TACLUDE SYSLIB(SQPL1A) TEST SUESYSTEM cooooclic 
IACLUDE SYSLIB(SUPL15) TEST SLBERCLTINE coo0ccec 
INCLUDE PLILIB(CIBMBPIRA) PLI SUEKOUTINES ccooceg3ec 
IACLUDE PLILIB(IBMBEERA) . oucocual 
TACLUDE PLILIBCIEMBERRA) e o0ocvocdsC 
INCLUDE PLILIB(IBMBBGKA) ooooocec 


IACLUDE SYSLIB(BTAMS1M) BTAm SIMULLATOK ccCcou7e 
INCLUDE SYSLIB(S1IM3270) SCREEN FRINTIANC cccuousc 


/* 

JLAFPSASSS ASH SEHK SSE HHSHHH HK K ES HH SHEESH HHH HSE SKK HEHE SHER EKER RETR HEED 
//* LINK EDIT THE TEST INTEKCUMM SYSTEM. 

//* NOTE THAT TRE INTERCOMP LKEDT PROC PLACES THE LCAO MCLULE CN bd 
4/% THE PMODSCR LLAD LIipRakY CREATED aABCVE. ’ 
//* 1T 18 NGT NECESSAKY TO KE=0C THE wkKCLe LINK TC wEPLACE 1 MOLLULE * 
4/4 IN TFIS CASE, ALL YOU ShHOULL vO 153: * 
//* 1) REASSEMBLE OR RECOMPJ]LE THE CHANGED NEw PCDOLLE IATC A * 
//* SEPARATE LOAD LIBRARY * 
4/* 2) CHANGE THE SYSIN DD STATEMENT TC //SYSIN CL * * 
//* FOLLOW IT bITH INCLUDE CARES ad 
4/1 FOR THE MODULES YGu wlSk Tu KEPLACE , 
//* 3) FOLLOW THOSE INCLUDES wITH THE FOLLOmINC 2 CARLS: . 
ie INCLUDE SYSLMOD(SIMICCM) bd 
//* EATKY PRISTUP * 
//* NAME SIMICUM(K) ad 
4/4 4) INSERT A DO STATEMENT FORK Tre LOAD LIEKAKY Ch wakiCr TEE * 
//* REPLACEMENT MOCULES RKESICE , 
//* 5) CHANGE THE RESTART PARM ON TRE JOB STATEMENT » 
//* TG POINT TO THE LKED.LKED STEP. * 
J/FPFPTHSHSIHERHHS ES SRH KEK HERPES KH SHES TSP RHEE THRE KTH HERP RET T ER ER RKTT HD 
//LKEL EXEC LKELDT,O=TESTyLPUDSSIMICEM, 

// PARM.LKED#**LISTeLETsXREF sNCALsSIZES(ZECKy1UGK}! 

J/SYSIN DD DSN@EEINCLESIMLINK) sCISF&(O.Le PASS) 

//PLILI¢ CD DSNSSYSaePLIBAScevISP#SHR Pel RESIDENT LIDRARY 
J/POCREL DE OSN=INTeMUDKEL sLISP#SnR 

41% 


Figure 53. Linkedit and Execution JCL for Simulation Mode (Page 2 of 3) 
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LLPOSOS HOO SET ESESH EHH EST HEEHE SHES OTHE SHH HHEHSEHESTHHEHESEE SHOT ENEEHHOH EE TESS 
fe EXECUTE INTEKCOMM IN SIMULATION MODE . 
LLPOESHSHHSHE SEH HS OHS SHOT SHES HOHE HET OHHSHHESHES HOSE HOF OOH THOT ESHO THEE HENEHS 
4/60 EXEC PGM=SIMICOMsPARM=*STARTUP® »TIME=( 920) 
J/STEPLIB OO OSN=INT.MODSCRUISP=(CLOsPASS) 
OSN#@ INT. MODLIBsDISP#SHR 
OSN#INT.MODREL pDISP=SHR 
OSN#SYSL.PLIBASE »DISP*SHR PLI RESe LIBRARY 
//INTERLOG DD DSN=EEINTLOGsDISPSINENS PASS) 
//- DCB#IDSORG#PS ,RECFM#VBySLKSIZE #4096 ,LRECL=40S2,NCPHOsCPTICD#C) » 
J/- SPACES I(TRK5(10,5) ),VOL=SER=INT1LOO pUNIT#=SYSCA 
//SLGG DD SYSCUT#A,DCBH(DSORG#=PS pBLKSIZE@12C »RECFMBFA) 
//STSLOG DD SYSCLT#A,D0CB#(OSORG@PS pBLKSIZE@126 pKRECFM=FA) 
J/SYSPRINT DO SYSCLT@A,DCB=(0SGRG@PS pBLKSIZETL41 sLRECL 2127 ,RECFM=VA) 
//RCTCOO DD OSN#INT.RCTOOO sDISP=SHRyDCB=(DSCRG=CA,CPTCC=RE } 
//PMIQUE DD DSN=INT.PMIQUE sOCdH(DSORGDA,OPTCO#k) sDISP=ShR 
//8TARQ GD OSN=INT.BTAMO,0CB=(0 SORG@DAsCPTCC#®R)sDISP=ShHR 
J/INTSTOR2 OD OSN=INTSTOR2Z,OCBH(DSCRG=DA,CPTCDO@EF gLIMCT#3) »CISP#ShHR 
//INTSTORI DO DSN@INTSTOR3 DCB S(DSCRGBCA,GPTCDSEF sLIMCT#2) pUISPSSER 
//* TEST DATA SETS FCR SAMPLE SUBSYSTEM 
//STOKFILE DO OSN*VSAMSD1.STCKFILE CLUSTERsDISP=CLD> 
4/ AMP= (AMORG, "RECFM=F') 
//PARTFILE OO DSN@INTBETA.PARTFILE »DISP=QLD9 
4 OCB=(DSORG=DA,OPTCD=R) 
//e¢ DATA SETS FOR SIMULATED TERMINAL -= TESTL 
J/TESTL DO DSN®INT.TTESTIs0CB=DSGRG=PS ,DISP*GL0 
//SCRTIEST1 OD SYSCUTSA,O0CB=(DSORG=PSyRECFM@FA yBLKSIZE=121) 
//SIMCARDS DOD * 
TEST1,001 
//FMISTCP OD OUMMY DELIMIT INTERCCAM FILES 
ase FAR PARAMETERS 
//¢ (TO USE, CHANGE ICCMIN TO DD *» FCLLCW wITH FARS INLINE) 
//1CCHMIN 00 DUMMY 
//* CYNAMIC LINKEDIT CATA SETS (1F NEECEC) 
J/OYNLLIB OD DSN#INT.MGDSCR sCISP=(OLDsPASS) 
//CYNLPRNT DO SYSCUT#A 
J/CYNLWORK OD UNIT#SYSDAsSPACEBICYL yy (lol) bsOTSP=( PASS) 
4/¢ 
J/STEPCAT OD DSN#=VSAMSD1,D0I1SP=SHR (1F NEECEC) 
//SNAPDO OD SYSOUT*A,SPACE@(CYL»)5) »FREE=CLOSE 
J/SYSLOUMP DDO SYSCUT®A 
//PLIOUMP DOD SYSCUT#=A (1F NEECEO) 
ss 
//ABNLIGNR OD OUMMY FORCE ABEND-AID TO IGNORE DUMP (PRCOLCE IBM DLP) 
LL POSES HOOT SOOO EEO DESEO EH OOOOH SEE ESET SOO OSH OOD EE HEROES HER EH EOE OEE ED 
4/% PRINT INTERCOMM LOG GENERATED 8Y THE TEST * 
LLPOCOSEEE SEE SOO SEE EHES HOOT ESEEO EES THSEOESH SOSH OHO OTE SESE TH EOE EOE DESEO SD 
/J/INTERLCG EXEC PCMSLOGPRINT »COND@EVEN 
J/STEPLIB OD DSN= INT.MODREL »DISP@=SHR 
J/SYSPRINT DD SYSCLT=A,OCB=(DSORG=PS »BLKSIZE=121) 
J/INTERLOG DD DSNSEEINTLOG,OISP=0L0,0CB=BLKSIZE=5CCO 
J/SYSIN 00 DUMMY 
// 


Figure 53, Linkedit and Execution JCL for Simulation Mode (Page 3 of 3) 
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Figure 54. SIM3270 Printout from Simulation Mode Execution (Page 1 of 22) 
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Chapter 12 


SUBSYSTEM TESTING IN TEST MODE 


12.1 INTRODUCTION 


All of the testing functions may be performed using the Intercomm 
Test Mode of operation without a Front End defined. Rather than 
receiving messages from a terminal, the Test Monitor reads messages 
into the system from a card-image data set. Snaps of input (snap 
ID=15) and output (snap ID=20) messages constitute a history of Test 
Mode execution. Essentially, the Front End is replaced by the Test 
Monitor (PMITEST) to drive the Back End as usual. In this way, 
subsystem testing can be going on in one or more regions or address 
spaces without affecting the on-line system. Figure 56 illustrates a 
sample reentrant PL/1 subsystem (SQPL1) designed for the same purpose 
as SQPLIA, but using the Edit, Output and Change/Display Utilities. 


12.2 TESTING A SUBSYSTEM IN TEST MODE 


To add and test an application subsystem in Test Mode, do the 
following: 


NOTE: Steps preceded by an asterisk (*) may often be performed 
for the application programmer by an installation’s 
Intercomm System Manager. Appendix C summarizes the 


Intercomm Table entries. 


1. Compile and linkedit the application program. Appendix A 
sescribes Intercomm-supplied PL/1 JCL procedures. 


*2, Create or add to a USRSCTS member on a user test library to 
contain a Subsystem Control Table Entry (SYCTTBL macro) which 
describe the subsystem. Reassemble and link INTSCT which 
copies the USRSCTS member from the test library (see Figure 
57). 


*3. Create or add to a USRVERBS member on the user test library 
to contain an Edit Control Table (VERBTBL) entry for editing 
of input test messages by the Edit Utility. Reassemble and 
link PMIVERBS which copies the USRVERBS member from the test 
library (see Figure 57). 


*4. %If a Fixed Format output message (VMI=X'72') is created for 
processing by the Change/Display Utility, code an entry for 
the CHNGTB (see Figure 57) to define the DESOOO data set 
entry number for the File Description Record (DESOO001--see 
Figure 58). The PMIEXLD utility must be used to load the FDR 
to the DESOOO file (see the Utilities Users Guide and the 


Operating Reference Manual). 


Chapter 12 Subsystem Testing in Test Mode 


5. Code, assemble and link and add an INCLUDE statement for the 
OFT load module RPTnnnnn (RPTOO100 and RPTO0501--see Figure 
58) to the Output Format Table (PMIRCNTB) in the Test Mode 
Intercomm linkedit for output message formatting by the 
Output Utility. 


6. Prepare test messages via the SIMCRTA utility or as direct 
card-image input data (SYSIN data set). An input test 
message consists of a header card, detail cards, and a 
trailer card, grouped together as illustrated in Figure 60. 
Figure 59 details the required card formats. The message 
area in the Test Monitor will accomodate a message text up to 
958 bytes long. Longer messages would require a modification 
to the Test Monitor (PMITEST), as described in the Operating 
Reference Manual. 


*7,. Add control cards to the Linkedit deck for the user program, 
unless the subsystem is dynamically loadable (see Figure 61). 


*8. Linkedit to create an Intercomm Test Mode load module (see 
Figure 61). 


9. Create test data sets and add DD statements for them to the 
execution JCL. 


10. Execute in Test Mode with test messages in card-image format: 


a. Single-thread test the subsystem; to test a reentrant 
subsystem, initially specify MNCL=l on the subsystem's 
SYCTTBL macro. 


b. Multithread test a reentrant subsystem (change MNCL) 
using several test messages. 


Test Mode execution is activated by the parameter ‘TEST’ on 
the Intercomm EXEC statement. Figure 61 illustrates a sample 
execution deck with test message input (DD statement SYSIN) 
for the sample inquiry program and JCL to print the system 
log. 


The resulting snaps for the test mode execution of the sample 
inquiry subsystem are illustrated in Figure 62. 


The System Log printed after executing in Test Mode with the 
sample inquiry subsystem is shown in Figure 63. 


ll. Test the subsystem concurrently with other application 
subsystems. 


Note: to implement the sample subsystem for on-line execution, it 
would be necessary to code a BTVERB macro (in USRBTVRB--see 
Chapter 11) as follows: 


BTVERB VERB=RTRP, SSCH=R,SSC={P , CONV=18000 , EDIT=YES 


Chapter 12 Subsystem Testing in Test Mode 


STMT LEV kT 


7* PROCEDURE SQPL1 USING EDIT» 


CUTPUTs CRANGE/CISPLAY UTILITIES */ 


1 QO SQPL1is PROC CIN-MSG_PTReSPAsSCT RC) 
OPTIONS(MAINSREENTRANT)3 /® SUBSYSTEM ‘"RP' - INCUIRY %/ 


/¢ DEFINE TRE INCOMING PARAMETERS 


2 1 #0 OCL CIN_LASG_PTR, /* INPUT PARM 1 - INPUT MSG ADCRESS &/ 
SPAs 7* INPUT PARH 2 = SYSTEM PARK AREA &/ 
SCT) PTR /* INPUT PARM 3 = SUBSYSTEM ENTRY s/ 


OCcL RC FIXED BIN(31)3 /* 


INPLT PARM 4 = RETURN CODE s/ 


DEFINE GENERAL FIELDS LSEC IN TRE PRCCESSING OF AN INPUT ASG 


OCL 1 DATE,» 


/* OATE EDITING 


3 MCNTR CRAR(2)9 /* TO HOLD THE BONTR 9/ 
3 SLASF1 ChAR(1),5 fe SLASF o/ 
3 DAY CRAR(2)5 4/* TO FOLO THE DAY */ 
3 SLASM2 CFAR( 1)» /* SLASH / 
3 YEAR ChHAR( 2); 7* TO HOLO TRE YEAR 9%/ 

5 1 0 OCL CURRENTLFILE CHAR(E); 
4* CCATAINS FILE NAME TC BE ACCESSED 9/ 
6 1 0 DCL RBN CRAR(3); /* 3 BYTE RBN FOR BDAM READ 9/ 
7 1 0 OCL RBNWORD FIXEC BIN(21)3 /* FIELD FOR RBA CONVERSICA #/ 
8 1 0 OCL KEY_LFIELD CkaAR(8); /* wILL CONTAIN VSAF KEY 9%/ 
9 1 #0 DCL ERROR_LFLAG FIXED CECIMAL(1) INIT(O); /* ERROR FLAG &/ 
10 1 0 OCL COBPUT_LRETURN CHAR(2)3 7* COBPLUT RC %/ 
11 1 0 OCL CUT_LMSG_PTR PTR3 4* TO POINT TO OUTAREA 9/ 

! 
OUTAREA CHAR(200)3 /*TO CONTAIN AN OLTPUT/ERRGR MESSAGE 
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STMT LEV ANT 


7* INCLUDE PLIENTRY #/ 
ZLINCLUOE PLIENTRY | OOOO Peres esseaeee eee eeeeeeeeseseseeeeessseseseeesens 


13 1 0 ODECLARE (¢ SELECT, 
RELEASE, 
READ» 
WRITES 
GET» 

PUT, 

GETV, 

PUTY>s 

RELEX, 

FEQY, 

COBPUT, 

MSGCCL» 

FESENDs 

FESENOC, 

COBSTGRF» 

CONVERSE, 

LOGPUTs 

DBINT», 

PAGE, 

CBUILD, 

QOPEN» 

QREAD, 

QREADX, 

QwRITE, 

QwRITEX, 

CCLOSE, 

FECANODQ, 

FECMFOBK, 

FECMRLSE» 

MAPIN, 

MAPOUT, 

MAPFREE, 

MAPENO, 

MAPURGE» 

MAPCLR» 

OwSSNAP) 4* REL 1C s¢ 

INTSORTC, 7* REL 10 %/ 

INTSTCRE» 

INTFETCK» 

INTUNSTO) ENTRY OPTICNS (ASH INTER) 
SPST EOHH SHEESH ESES /* FCR CPTIMIZER = ASSEMBLER ENTRY PCINTS 8/ 
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STMT LEV NT 


/* DEFINE THE STRUCTURE CF THE INCOMING MESSACE #/ 
14 1 90 DCL 1 INPUT_MESSAGE BASECCINIMSCLPTR)» /* INMSG STRUCTURE *%/ 
3 INLHOR» #¢ MAP THE INPUT HOR @/ 


7* INCLUDE PLESGhD / 
LINCLUDE PLESGCHD; FOO Feet eres ee eee eee eee esse ES EE SETOHESEE SEO OS ES SEE HOES 
MSGRLEN FIXEC BIKC15) UNALIGNED, 
MSGHCPR CFAR (1)5 
BMSGFRSCH BIT (8) ALIGNED,» 
MSGrRSC BIT (8) ALIGNED, 
MSGFSSC BIT (8) ALIGNED, 
MSGFMMN BIT (24) ALIGNEDs 
MSGRDAT CRAR (6) 
MSGFTIM CrAR (8)9 
MSGRTID CrAk (5)5 
MSGHCON BIT (16) ALIGNED, 
MSGFFLGS CFAR (2) 
MSGFRBMN BIT (24) ALIGNED, 
MSGFSSCh BIT (8) ALIGNED, 
MSGRUSR CFAR (1)» 
MSGFAOOR BIT (16) ALIGNECSs 
MSGFLOG CRAR (1) 
MSGHBLK BIT (8) ALIGNED» 
MSGRVMI BIT (8) ALIGNED, 
SHETES STO EO SETEOS 7* STANDARC DEFINITION OF THE HEADER FIELDS o/ 


MNF FU VMN Fa 


3 IN_TEXT, /* PAP THE INPUT TXT ¥9/ 
5 PARTAGs 7* PART NUMBER WHCLE %/ 

7 TREPART PIC'SSS9%, 7* THE MAIN PART o/ 

7 RBNBYTE PIC'S*, /@ KEY BYTE =-BOAP %/ 


5 WHSAO PIC'SSS'; /* WAREFOUSE NLBBER o/ 
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STMT LEV NT 


/* DEFINE THE STRUCTURE CF A NCRMAL CUTGCING MESSAGE RESPONSE *#/ 


15 1 0 DCL 2 CUTPUT_MESSAGE BASEC(CLT_MSG_PTR)»y /*CUTMSG STRUCTURE®/ 
3 OUT_HDR» /* MAP THE CLTPUT HER @/ 
/* INCLUDE PLMSGHD */ 


ZINCLUDE PLESGHD; eh eseseses sess eset sees eee ee ese SESE TEH EH SHHOSEH OEE EOS 
MSGnhLEN FIXED BIAN(15) UNALIGNED, 

MSGFCPR CraR (1)> 

MSGFRSCH BIT (8) ALIGNED, 

MSGHRSC BIT (8) ALIGNED, 

MSGRSSC BIT (8) ALICNEC, 

MSGFMMN BIT (24) ALIGNED, 

MSGFOAT CrAR (6)5 

MSGRTIM CraR (8)>5 

MSGHTIO CraR (5)>5 

MSGrCUON BIT (16) ALICNECs 

MSGHFLGS CrAR (2)5 

MSGrBMN BIT (24) ALIGNED, 

MSGeSSCr BIT (8) ALIGNEC, 

MSGrRUSR CraR (1)>5 

MSGrADCR BIT (16) ALIGNEC, 

MSGFLOGG CAR (1)y 

MSGRBLK BIT (8) ALIGNECs 

MSGFYMI B1T (8) ALICKECs 

Bad dad anata /* STANCARC DEFINITION CF TRE HEADER FIELDS o/ 


MAM FTwMVwMwNwwww 


3 OLT_TEXT, /* MAP THE CUTPUT TXT 9/ 


FRTINAME CraR(1l2)5 /* FORMAT FCR Crh/CSP #/ 
PRTDATA CrAK(64)5 /@ PaRT NC OESCRIPT #/ 
PRIPRC PIC'S$$9V.5999', /* PART KC PRICE 9/ 
OUTwESAC CRAR(5)» /* STOCK WAREHSE NC e/ 
OUTSDATA, /*® |= WAREMCUSE INFC 9/ 


Ran wn 


7 WHSLCC CHAR(22)5 /* LOCATICN 9/ 
7 STKLEY PIC*2Z 22252295 /% STOCK LEVEL 9/ 
7 LEVCATE CrKAR(G)» /* AS GF = DATE 9/ 
7 STKORC PIC'ZsZ2225229%,/*% OAROER LEVEL o/ 
7 ORCOATE CHAR(8);5 /* AS OF = DATE 
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STMT LEV NT 


/* DEFINE THE STRUCTURE OF A EKRGR MESSAGE RESPONSE #/ 

OCL 1 ERRCR_MESSACE BASEC(OUT_LMSG_PTR)>» /*ERRMSG STRUCTURE®/ 
7* OVERLAY TRE OUTPLT MESSACE BY USING THE SAPE PCINTER %/ 

3 ERR_HDR, /* MAP THE ERROR HOR *%/ 


4* INCLUDE PLASGHD */ 
ZINCLUDE PLMSGHD; eS eee ee eer eee eee OT HT EEE HEHEHE SEE T RES OO ESE RE REDE HED 
MSGFLEN FIXED BIN(15) UNALIGNED, 
PSGFCPR CFAR (1)>5 
MSGHRSCr BIT (8) ALIGNED, 
MSGHRSC BIT (8) ALICNED, 
MSGFSSC BIT (8) ALIGNED, 
MSGFMAN BIT (24) ALIGNED, 
MSGRCAT CrAR (EJ) 
MSGFETIM CFAR (8) 
MSGRTID CRAR (5)5 
MSGFCON BIT (16) ALIGNEC, 
MSGHFLGS CFAR (2), 
MSGFBMN BIT (24) ALIGNED, 
MSGrSSCr BIT (8) ALIGNED, 
MSGHUSR CFAR (1)5 
MSGFADOR BIT (le) ALIGNEC, 
MSGRLOG CAR (1)5 
MSGHBLK BIT (8) ALIGNECs 
MSGHYMI BIT (8) ALIGNED, 
SUS HTE HSH REE SESE /* STANDARO DEFINITICN OF TRE HEADER FIELDS 


5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 


3 ERR_TEXTs /* MAP THE ERROR TEXT 
5 ERRCRFEMT,» /* CRAR FORMAT CUTPLT 
7 ERRCRIRPT CRARI7),5 /* REPORT ITEM/LEN 
7 ERRCR_RPTNO FIXED BIN(15) UNALIGNEDs 
/* REPCRT NUMBER 
7 ERRCR_LITM CFAR(7)5 /* TEXT ITEM/LEN 


5 ERRORTXT CrAR(5C); 7* ERROR FPESSAGE DATA 
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STMT LEV NT 


/* DEFINE THE FIELOS NEEDED FCR FILE ACCESS USING THE FILE HANOER 


OCL 


1 FHLAREAS ALIGNEC, 7* FILE FANOLER CONTROL AREAS ¢/ 


3 FH_LOUMMY FIXEC BIN(31)5 /* FOR ALIGNMENT s/ 


3 EXTOSCT CHAR(48),5 /* EXTERNAL OSCT s/ 
3 FHCW, /% CONTRCL wORDeoe %/ 
5 FrCwl CHAR(1)>» /* ee BYTE 1 / 

5 FRCw2 CHAR(1)» v* ee eBYTE 2 / 

5 FrCw3 CrARCL), /* ee eBYTE 3 o/ 

5 FHCn4 ChAR(1); /* seeBYTE 4 s/ 

18 1 0 DCL 1 PART_RECORC, /* 1CC BYTE BC4M RECORO WITHCUT KEYS #/ 
3 P_LREC_PART_DATAy /* PART INFOcee o/ 
5 P_LREC_PIN PIC*'(5)G"» /* eee THE NUMBER s/ 

5 PLREC_LDES CHAR(54)5 J* eee THE DESCRIPT. %/ 

5 P_LREC_UAT CHAR(5)>5 /* eee THE ORDER UNIT %/ 

3 P_LREC_PRC FIXED DECIMAL( 754), /® PRICE OF A UNIT o/ 
3 P_REC_MFR_NUM CEAR(15)>5 /* MANLFACT. NUMBER &/ 
3 PLREC_LFILLER CHAR(17)5 /* FILL TO 100 BYTES #/ 


STOCK_RECORD, /* €0 BYTE VSAM RECORD $/ 


3 DELETE_CHAR CFARI1); ¢ / 
3 S_LREC_KEY_FIELC, /* THE KEY TO FILEooe %/ 


5 S_LRECLWHS PIC'(2)S", J* eee WAREFOUSE ALBe #/ 
5 S_RECLPNC PIC'(5)S", /* eee PART NUMBER o/ 


3 S_RECLFILLER CHAR(28)5 tid s/ 
3 SLRECLSTCCK_CATA, /* STOCK DATA FOR «ee %/ 


S_REC_WLC CHAR(23)5 /* WAREHOUSE LOCATICN */ 
S_REC_LEY FIXEC DECIMAL(7)5 
/® AMOUNT IN STCCKeeoe #/ 


5 
5 


5 S_REC_LOT CARE)» /* see AT DATE o/ 
5 S_REC_CRD FIXED CECIMAL(7)5 

7* ORDER NEEDS eee */ 
5 S_REC_ODT CKAR(E)3 /* «ee AS OF DATE o/ 


OCL 


1 FILELNAMES STATIC») /* FOR CALLS 10 
3 DD_STOCK CHAR(8) INITC'STCKFILE')» 
3 OD_PART CHAR(&) INIT(OSPARTFILE' D5 


THE FILE FANDLER 
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/*® THE MAINLINE ROUTINE - LEVEL ONE CF SCPL1 


MAINLINE? OG; 
RC = 03 /* INIT TRE INTERCOMM RETURN COOE 


/* SET LP ThE GUTPUT HEADER FIELCS 
OUT_MSG_PTR = ADOR(OLTAREA); /* FCINT TO GUTPUT AREA 


OUT_HOR = IN_KODR; 7* COPY INHOR TO OUTHER 
CUT_HDR.MSGHLEN = 185} /* OUTPUT MESSAGE LENGTH 


OUT_LHOR.MSGHOPR = '2'3 7* OLTPUT PESSAGE QPR 
OUT_LHOR.MSGHVFI = "C111CC1C'B; 


/* CUTPUT MESSAGE VMI x'72' 
CUTLHOReMSGHRSC = "11CC10CC"B; 


/* GUTPUT MESSACE RSC Ctr’ 
CUT_HOR.MSGHRSCH "'8; 7* OUTPUT MESSAGE RSCr x*OCc?* 
CUTLHDReMSGHSSC = IN_LHORePSGFRSC; 


7* RECEIVING TO SENOING 
OUT_HOReMSGHSSCH = IN_HOR«MSGERSCh3 


7* RECEIVING TO SENDING 


7* NOW LETS READ THE PART RECCRO FILE (8DAM) LSING INPLT PART NC 
CALL BDAM_READ; 7* CALL PROCEDLRE TO CO RECUEST 


IF ERROR_LFLAG ae /* IF FILE SELECTED, RELEASE IT 
THEN 


D0; 


STRING(FECW) = * 5 


/*® INIT FRHCw FCR CALL TO RELEASE 
CALL RELEASECEXTDSCTsFHCH); 


/* ALWAYS RELEASE THE FILE 


ENO; 


IF ERRCR_FLAG a= C /* BOAM READ ROUTINE FAIL 2 
TREN LEAVE MAINLINE} /* YES» LEAVE THE MAIN LINE 
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STMT LEV AT 


7* ALL IS OK SO FAR — SO LETS GO AND CETAIN A STOCK RECCRO BY 
/* READING THE STOCK FILE (VSAM) LSIAG THE WAREFCUSE IN THE KEY 


CALL VSAM_LREADS 7* CALL PROCEOURE TO OO RECUEST 


IF ERROR_FLAG a= 3 /* TF FILE SELECTED, RELEASE IT 
THEN 


00; 


STRINGUFFCW) = ° "3 


/* INIT FrkCr FOR CALL TO RELEASE 
CALL RELEASECEXTCSCTy»FRCR); 


7* ALwAYS RELEASE TRE FILE 


ENO; 


IF ERROCR_FLAG am Q /* WSAM READ ROUTINE FAIL 2 
TREN LEAVE MAINLINE? /* YES» LEAVE THE MAIN LINE 
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C 


STMT LEV NT 


44 


45 


46 


47 


60 


61 


62 
63 


64 


65 


Oe od oe 


~ 


/* ALL FILE 1/0 IS SUCCESSFUL - 


Subsystem Testing in Test Mode 


ACw BUILC TRE CUTPUT MSG RESPCHSE 


/* FIRST LETS INITIALISE THE FCRMAT NAME FCR CHANGE/DISPLAY 


FMTNAME = 'SSRCOQ001C 


/* 


SET UP FORFAT NAME 


/* NOW LETS GET THE WAREHOUSE ALMBER FROM TEE INPLT AND EXPAAD IT 


ee ee 


J 


NN 


Figure 56. 


OUTWHSNO = ' "$3 gnWrSA 


G; 


/* 


SET UP WhS NUMBER 


/* GBTAIN INFORMATION FROM THE PART RECORD JUST READ 


PRTOATA = STRING(P_REC_PART_DATA); 
7* PART DESCRIPTION TO CUTPUT AREA 
/* PART PRICE TO 1/0 BSG 


PRTPRC = P_REC_PRC3 


7* OBTAIN INFORFATICN FROF TRE STOCK RECORD JUST READ 


WHSLOC = S_REC_WLC; /* 
STKLEY = S_REC_LEV; /e 
MONTH = SUBSTR((S_REC_LOT)slyz)3.0/® 
DAY = SUBSTRUGS_REC_LCT) 939203 ye 


YEAR = 
SLASHlL> SLASH2 = */°; 
LEYDATE © STRING(CATE 
STKORO = S_REC_ORC} 

MONTH 


YEAR = 


ORDDATE = STRING(DATE 


SUBSTRI(S_REC_LOTI1592)3 


= SUBSTRIGS_RECLODT)I5152)3 
DAY = SLBSTRI(CS_REC_COT) 9352)3 
SUBSTRICS_RECLCOTI1552)3 


/* 
/? 
/* 
/* 
/* 
/* 
/* 


4/4 NCTE 


/* 


MCVE TRE LOCATICN 
MGVE STCCK LEVEL 
EXTRACT ThE MCNTr 
EXTRACT THE Day AC 
EXTRACT TFE YEAR 
MGVE IN TRE */°S 
MCVE LEVEL DATE 
MOVE ORCER LEVEL 
EXTACT TFE MONTH 
EXTRACT ThE ODay AO 
EXTRACT THE YEAR 
‘/"S IN ALREADY 
MCVE STOCK DATE 


/* CUTPUT MESSAGE 1S ACh BUILT = LETS SEND IT USING COBPLT 


CALL COBPUTICLTPUT_PESSACE sCCBPLT_RETURN); 


IF COBPUT_RETLURN 
THEN 
0a; 


as 


ERROR_FLAG = 23 
LEAVE MAINLINE} 


END; 


END MAINLINE; 


*cc? 


/* CUTPUT QUEUING FAILURE? 


/* 
/* 


EKO CF THE 


fe YES 


SET SERIGUS ERRCR 
THATS IT FOR ACh 


MAIN LINE ROUTINE 
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STMT LEV NT 


! 


/* CONTROL COMES HERE AFTER EXECUTICN OF THE MAIN LINE ROUTINE t= #/ 
7* CHECK IF ERROR_FLAG HAS BEEN SET AND IF SO SEND APPROPIATE / 
/* ERROR RESPONSE *#/ 
| 66 1 0 SELECT (CERRCR_FLAG}; 
67 Ses WHEN (0)35 /* OK» NO ACTICN */ 
68 : 1 WHEN (2) 7* INTERCCHM SERVICE ROUTINE FAILLURES/ 
OC; 
69 1 2 RC @ 123 7* LET INTERCCRHM SEND ERRCR MESSAGES/ 
70 1 2 END; 
71 es WHEN (3) 7* FILE COULD NOT BE SELECTED - NO CCCARC? #/ 
OG; 
72 1 2 ERRORTXT = CLRRENT_FILES 3 
* - FILE CCLLD ACT BE SELECTEO's /* SET TEXT #/ 
73 1 2 CALL SEAD_ERR_MSG; 7* SEND THE ERRCR MESSAGE #/ 
74 1 2 END; 
75 t 2 WHEN (5) 7* RECURC NOT FCUND IN FILE #/ 
0d; 
76 1 2 ERRORTXT = *PART "IESTRINGCPARTNOD GE] 
" NOT FCUNCS; /* SET TEXT #/ 
77 1 2 IF CURRENT_FILE » CC_STCCK 
THEN 
00; /* SUPPLEPENT TEXT IF STCCK FILE ERRCR */ 
78 1 3 ERRCRTXT @ SLBSTRICERRGRIXTIsle20)i: 


* IN WAREHCUSE “TEWHSNO; /* RESET TEXT#/ 


END; 


ELSE; 


CALL SEAD_ERR_MSG;3 7* SEND THE ERRCR MESSACE %/ 


END; 


END; /* END SELECT e/ 


RETURN; 


/* LEAVE SQPL1 - ALL DOME *#/ 
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STMT LEY NT 


/* PROCEOLRE TO READ Tre 8CAP FILE = DDONAME=PARTFILE 
BOAM_READ?: PROC; /* READ BOAM FILE BY RBN 


RBNWORD = RBNBYTE; /* CONVERT OIGIT TO BINARY 
UNSPECURBN) © SUBSTRILNSPECURBNWORD ) 95524)5 

/* SET RBN UP FOR READ = ABMLST BE 3 BYTES 
CURRENTLFILE = DD_PART; /* SET FILE TO BE ACCESSED 
STRING(FHCW) = * "; /* INIT FILE FANOLER CONTROL WCRO 
UNSPECCEXTDSCT) = °°B8; 


/* INIT FILE FANDLER CCNTROL BLOCK 


CALL SELECTCEXTOSCTsFrCw,CLRRENT_LFILE); /* SELECT FILE 


IF FHCWL = '9§? /* SELECT ERROR 7?» NO CC 
TREN 


OO; 


ERROR FLAG = 3; /* YES = SET BAC RETURN COCE 
RETURN; 


END; 


STRING(FHCW) = ° 5 /* SELECT CK» INIT FrCw FOR READ9/ 


CALL READLEXTCSCT,»FrCwyPART_RECORD »RBND| 
/* 8C4m READ BY REN &/ 


IF FHCW1 a= ‘OC /* CHECK RE#O RETURN CCCE #/ 
TREN 


00; /* FF ALL IS Ck» OO NOTHING *%/ 


ERKOR_FLAG =2; /* OTHERWISE SET ERRGR FLAG 9/ 
RETURN; /* AND RETURA #/ 
END; 


IF STRINGOPLRECLPIN) «= STRINGCPARTNO) 
/* 1S PART NUMBER CH FILE SABE AS INPUT PART NUMBER? 
TREN 


00; 4* KC MATCH = TREN PART NUMBER NOT FCUAD 


ERROR_FLAG = §;5 /* SO SET TrE ERROR FLAG 
RETURN} /* AND RETURN 


END; 


END BOAR_READ; 
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STMT LEV NT 


/@ PROCEDLRE TC READ TRE VSAM FILE = DCNAME=STOKFILE 9/ 


107 1 OQ VSAM_READ: PROC; /* REAC WSAM FILE BY KEY 9/ 
108 2 0 SLREC_LWHS = wWrSNQ; /* wWhSNO IS PART OF THE KEY #/ 
109 2 0 STRING(S_REC_PNO) = STRING{PARTAC); 
/* PARTNC IS PART CF THE KEY 9/ 
110 2 a KEY_FIELO = STRING(S_REC_LKEY_FIELCI; /* THE WSAM KEY 9/ 
111 2 0 CURRENT_LFILE = OD_STCCK; /* SET FILE TQ BE ACCESSEC */ 
112 2 0 STRING(FHCW) = ° "5; /9 INIT FILE FANDLER CONTROL WCRO #/ 
113 2 a UNSPEC(EXTOSCT) = "'8; 
/¢ INIT FILE FANDLER CONTROL BLOCK ¢/ 
114 2 0 CALL SELECTCEXTOSCT,»FRChwsCLRRENT_FILE); /* SELECT FILE 9/ 
115 2 0 IF FHCwl = "9! /* SELECT ERROR ?5 NO CO es 
TFEN 
| OQ; 
| 
; 116 21 ERROR_FLAG = 2; /* YES = SET BAD RETURN CODE ¢/ 
117 21 RETURN; 
118 21 ENO; 
119 2 0 STRINGCFHCH) = ! 5 7* SELECT CKy INIT FrChw FOR READS 
120 2 0 CALL GETV(EXTCSCTsFRCh sSTCCK_RECCROsKEY_FIELC); 
/¢ VSAM READ BY KEY 9/ 
121 2 0 SELECT (FHCW1); /* SELECT GETY RETURN COCE */ 
122 24 WHEN (°O°)3 /* TF jue IS CKsy LEAVE O %/ 
123 24 WHEN ('2°) 
DO; 
124 2 2 ERROR_FLAG = 53 7* RECORD NCT FOUND SET 5 */ 
125 2 2 END; 
126 21 OTHERAISE 
dO; 


ERROR FLAG = 2; /* ANY OTHER ERROR SET 2 9/ 


ENO; 


END; 
ENO VSAM_REAO; 


END SELECT 
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STMT LEV NT 
/* PROCEDURE TO SEND AN ERRCR MESSACE 9/ 
131 1 © SEND_ERR_MSG: PROC; 
/* RESET ERROR HEADER FIELDS TO SENC MESSAGE TO TRE CUTPUT UTILITY 9/ 
/* NOTE THAT ERROR MESSAGE HEACER FIELCS ARE MOSTLY SET AS THEY */ 
/7* OCCUPY ThE SAME STORAGE AS ThE STANDARD QUTPLT HEADER = BOTH 9/ 
7* STRUCTURES USING THE SAME FCINTER. MCOIFICATICN OF THE CRANGED °/ 
/* FIELDS IS ALL THAT IS NECESSARY. */ 
132, 2~«~OO ERR_HDR.MSGHLEN = 108; 7* SET ERROR MESSAGE LENGTH */ 
133. 2 «0 ERR_HOR.MSGHRSC = "111001CC'B; 7* SET QUTPLT UTILITY 9*/ 
134 2 0 ERR_HOReMSGHYMI = "C1C1OOCC'B; 7* SET CUTPUT WEI 9/ 
7* SET THE REPORT NUMBER AAC ITEM COCE FIELGS FOR CUTPUT UTILITY */ 
135 2 :«O ERROR_RPT = "255CC3N'G 7* CRAR FORMAT FOR X'FFO2' 9/ 
13602 —«OO ERROR_RPTNO = 5013 7* RALFRCRD BINARY '5Cl* = 9/ 
137. 2:~«OO ERROR_ITM = '"249C51N‘5 7* CrAK FORMAT FOR X'F932" 97 
7* DATA TEXT WAS SET LP BY TRE CALLER - ACh READY TO CALL COBPLT 9/ 
138 «62 «(OO CALL COBPLT(ERROR_PESSAGEsCOBPLT_RKETURN) 
139 2:(«OO IF COBPUT_RETURN a= ‘CO! 7* CUTPUT QLEUING FAILURE ¢/ 
THEN /* YES 9/ 
DO; 
140 2 1 RC = 123 /* COBPLT FAILED, IC SENDS A MESSACE 9/ 
144.621 END; 
142,02 «00 END SEND_ERR_PSG3 
;} 143 1 0 END SQPL1; ye TRATS ALL FOLKS */ 
{ 
| 
STORAGE REQUIREMENTS 
BLOCK, SECTION OR STATEMENT TYPE LENGTH (REX) DSA SIZE | (EX) 
*sSQPL11 PROGRAM CSECT 1540 194 
*sSCPL12 STATIC CSECT 356 164 
SQPL1 PROCEDURE BLOCK 846 a4E 3c8 
BOAM_READ PRCCEDURE BLOCK 464 100 E8 
YSAM_REAO PROCEDURE BLOCK 388 184 Ea 
SEND_ERR_MSG PROCEDURE BLOCK 238 EE pO 


Figure 
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//TABLES 
DEFINE SYCTTBL FOR SUBSYSTEM 


//STEPL EXEC LIBELINK,Q=TEST,NAME=INTSCT , LMOD=INTSCT 

//LIB.SYSIN DD * 

./ ADD NAME=USRSCTS 

./ NUMBER NEW1=100, INCR=100 

USRSCTS DS OH 

RP SYCTTBL SUBH=R, SUBC=P, SBSP=SQPL1, LANG=RPL1, OVLY=0, 
NUMCL=10 , MNCL=1 , TCTV=60 , SPACE=4096 

/* 

//ASM.SYSIN DD DSN=INT.SYMREL(INTSCT) , DISP=SHR 

//* 

//* DEFINE EDIT CONTROL TABLE ENTRY 

//* 

//STEP2 EXEC LIBELINK,Q=TEST, NAME=PMIVERBS , LMOD=PMIVERBS 

//LIB.SYSIN DD * 

./ ADD NAME=USRVERBS 


./ NUMBER NEW1=100, INCR=100 

USRVERBS OH 

RTRPECT RTRP,D9,256,2, FIX=YES 
P/N,1,7,5,10000111 
WHS ,2,7,3,10000111 


/* 
//ASM.SYSIN DSN=INT.SYMREL(PMIVERBS) , DISP=SHR 
hie 
//* DEFINE CHANGE/DISPLAY TABLE 
Lp* 
//STEP3 EXEC LIBELINK,Q=TEST , NAME=CHNGTB , LMOD=CHNGTB 
//LIB.SYSIN DD * 
./ ADD NAME=CHNGTB 
./ NUMBER NEW1=100, INCR=100 
CHTB TITLE 'CHNGTB - FIXED FORMAT OUTPUT-DESCRIPTOR NAME TABLE’ 
CHNGTB CSECT 
DC CL8’‘SSRQO001' USED ONLY TO TEST PL/1 PGM. GUIDE S/S 
DC F‘Q' 
PMISTOP 
END 


Figure 57. Table Updates to Implement Test Mode Testing 


Test Mode 


ing in 


Subsystem Test 


Chapter 12 


Gb=OlL* REaWOdd*9T #9009 

GE=DOL*TE=WOA4S 40 SVe=VLV08SS2=39009 
F2201°GT=WOdd*'ST #3009 
ET#IL*9=WOdd*, HdCHO NOe#VLV0'SS2%#35099 
beSWALT*S8=WNN 

Gba0l* BEawhdd* oT #3009 

GE=IJLSTEBWONSS AD SViEVLVO'SGG62=9009 
E2=Ol*GTswOudS€T=#39099 

2THILS9aWONds pONVH NO, eV LV0°S62#49099 

be SWAILIS2=WNN 

GEsOLlLSE€tT=WOddSOT #3009 
TT=JLS>=WOdd* NOTLVIOT eVLVd'SS2=35009 
Z=eSWILTS9=WNN 
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Z=SWILTSE=WNN 

LTsOLSET=WwOdd*2T=3009 

TT#OLSTeW9dds pYIAWAN LdVds #V1V08S662#3909)9 
Z=SWILI*2=WNN 

G2s91S9sWOddS e LSIIOAM SNLVLS AIOLS»=VLvdsss2=49009 
T=SWILt* T=WAN 


Ng 
WILT 
WILT 
WALT 
WILT 
ANI 
WALT 
WALT 
WILT 
WILT 
3NI1 
WILT 
WILT 
JNT1 
WALT 
WALI 
JNT 
WALT 
WILT 
WALT 
WALT 
JNT1 
WALT 
WALT 
ANT 
WALT 
WILT 
INIT 
WILT 
INIT 


B=SINITOOT#WNN LYOdad 


LVN9OTO 


aquost) 


LaW+T) 


AJTETI 


ITHOTI 


SHMR) 


JUd6oT) 
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OOTLAD 
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9T#IONIS XXLOO=AWVNS RANA TS22T#139S450 
GT=3009* XXGYO*IWVNS 62N371°8TT#L49S40 
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WALSASANS AAMINONI JATdWVS WOU 


ana 
11304 
T1394 
T1404 
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TRAILER 
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ee Da 


Contents 


2S SS SS Sa SS SS SS SSS SS SS SS SS ESS eS ee 


VMI value (MSGHVMI); leave blank if EDIT 
required; code 255 if no editing by Edit 
Utility (or 57). 

Data for one line of input message, If VMI 
in header card is left blank, a new line 
character is inserted at end of text on every 
card except last one. If the last non-blank 
character is a $ sign (X‘'5B’), it will be 
replaced by a NL; the preceding character 
(usually a blank) is kept as part of the 
input. All NL’s are suppressed if editing is 
not required. 

Generates End of Transmission character 
following the last non-blank character of the 
previous detail card. 


Contents Ending 

of Card Character 
EMS EOT (X'37') 
EOT EOT (X'37') 
ETX ETX (X'03') 
ETB ETB (X'26') 


*3-digit integer values (from 000 to 255) or a corresponding single 
alphanumeric character in low-order field position. 


**64 is default maximum. 
necessary to alter this specification. 


Figure 59. 


See the Operating Reference Manual if 


Test Mode Message Card Formats 
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MSG P 
RTRP 

P/N 12345 
WHS 200 
EMS 

MSG P 
RTRP 

P/N 55555 
WHS 200 
EMS 

MSG P 
RTRP 

P/N 12345 
WHS 300 
EMS 

MSG P 
RTRP 

P/N 12349 
WHS 200 
EMS 

MSG P 
RTRP 

P/N 12341 
WHS 100 
EMS 

MSG P 
RTRP 

P/N A2345 
WHS 400 
EMS 


Figure 60. Sample Input Test Messages for Test Mode 
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//EXECTEST JOB CICOMTEST 9920) 9'ICOM TEST SQPLI"sCLASS=Ay 
41 RESTART=(GENLINK ASP) 
//PROCLIB CD OSN#INT.PROCLIBsDISP=SHR (AS NEEDEC) 
J POOROR ERO TEETH EEE EEE EEE SEETHER EEE E EEE EET EOE SEE EEE ET EEEE SEES EE EEEE ES 
4/* THE RESTART PARM IN THE JOB STATEMENT RESTARTS TRE TEST AT THE * 
4/* BEGINNING. IF YOU WISH TC RESTART AT A DIFFERENT STEPs CODE * 
4/* RESTART=STEPNAME OR RESTART#STEPNAMEePRCCSTEPNAPE * 
44% * 
4/* WOTES WHEN USING A VSAM FILEs IT MAY BE NECESSARY 10 EXECUTE * 
41% IOCAMS TO VERIFY ThE FILE IF A PREVICUS EXECLTION ABENDED. * 
LL PPCREEH EAE EEE EE EERE EERE E ERE ETE HERE TEER E TEE ETE OPER ETE TEO REET ETEE EEE 
41% 
LS [POSSE OEE SEETHER ER EEE EEE SESE EEE SESE ETRE TEES OOF EEE REET EEE TES 
//* STEP GENLINK GENERATES A STANDARD TEST MOCE LINKECIT DECK * 
4% VIA ASSEMBLY OF THE ICOMLINK MACRO. * 
//* THE GENERATED DECK (TESTLINK) IS PLACED ON INT.SYMTEST. * 
S(PEREE EERE EEE EEE EEE EE EEESE SESE EEE EEE ERE ETTORE HERO E NETO ETERS EE 
//GENLINK EXEC ASMPC,Q=*LIBsU=REL »DECK=DECK 
J/ASB.SYSIN OD * 

ICOMLINK TEST#YESyMML=NO ySTORFCK#NO 

END 
J/SYSPUNCK DD DSN#INT.SYMTEST(TESTLINK) »DISP®SER 
//* 
L[ PETER AEEEEEE EEE EERE EEE TEER F EEE EEE TESTE EOE DETER ESET ESE EE REE EEEE ES 
4/* STEPS SCRSCR AND ALLOCSCR DELETE AND RE~ALLCCATE TRE LGAD * 
4/*% MODULE LIBRARY USED IN THE TEST (ALSO USED FOR CYNLLIb) * 
[ [PORTER EOE SHEE EEE EER EO EEE EOE EEE EEE TEESE EEO R EEE EDR OREO E EEE EERE 
//SCRSCR EXEC PGM=IEFBR14 
//FILEL OD DSN= INT.MOOSCR»sDISP=(OLDsDELETE) 
//ALLOCSCR EXEC PGM=IEFBR14 
4A OD OSN#INT.MODSCR sDISP#=(,CATLG) sUNIT#SYSCA, 
4/ DCB=INT.MODREL » VOL=SER#INTOOLsSPACE@(CYL 5 (3597)) 
/* 


NOTE: JCL requirements vary by installation requirements. The above 
example illustrates representative JCL. The installation 
System Manager should verify JCL to use. 


Figure 61. Linkedit and Execution JCL for Test Mode (Page 1 of 3) 
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YW OPP RPSE PER ES ESLER ELE ES ESSER EET ESSE EVE TESTE SEES EEE ES ESE ESE SSE SUE SS) 


//* STEP CENINCL CREATES INCLUDE CARCS USED BY TRE LINK ECIT STEP * 
//7* THE ADDED INCLUDE STATEMENTS ARE FOR THE SAPPLE SUSSYSTEM ANE * 
44 TRE REFERENCED OFTS (INCLUDE AFTER PMIRCATB). * 
//* YF TRE TESTI TERMINAL 1S NOT IN THE SYSTEP FRISTATB TABLE» LSEs * 
‘/* INCLUDE MODREL(PMISTATB) * 
UR ie INCLUDE MODREL(PMIDEVTB) * 
4s INCLUDE MODREL(PMIBROAD) * 
UR ie TRE ABOVE ASSUMES THE CONTRCL TERPFINAL IS NAMED CATO]. * 
//* *#* BEFORE THIS STEP, SEQUENCE NUMBER THE TESTLINK SOLRCE. *¥8*% # 
LLAMAS EE TOOT HH THOSE HHT HE OHHH HHO TSE SHH OOS T EC OH THEO OREO HERE OTHE E ES 


J/GENINCL EXEC PGM@IEBUPDTE 

J/SYSPRINT OD SYSOUT#=A 

JISYSUTL 00 OSN#INT.SYMTEST,DISP#SHR 

J/SYSUT2 CO DSN@EEINCL sDISP#lsPASS) sUNIT#SYSDAsSPACES(CYLs (lsloldde 


4/ OCBe(BLKSIZE#80,LRECL=60) 

J/SYSIN DD * 

ef CHANGE NAME@TESTLINKyLIST#ALL 
INCLUDE SYSLIB(SOPL1) SAMPLE SUBSYSTER ooo000lc 
IACLUDE PLILIB{(I8MBPIRA) PL/1 INTERFACE ROUTINE €C61050C 
INCLUDE PLAILIBCIBMBEERA) PL/1 INTERFACE RCUTINE €c611000 
INCLUDE PLILIB(IBMBERRA) PL/1 INTERFACE RCLTINE 00611500 
INCLUDE PLILIB(IBMBBGKA) PL/I INTERFACE ROUTINE 00€1200C 
INCLUDE SYSLIB(RPTOO100) DISPLAY OFT FCR SUBSYSTEM €198100C 
IACLUDE SYSLIB(RPTOO5O1) ERRCR MESSACES CFT 01982000 


LLTSCHSHSSOOSHSHHH SHS HSH SESS SESSESOSHSHESSEHSHREH HSH HS ETHOS SES EHR ETH HSE HEHEHE EHS 


Ue ied LINK EDIT THE TEST INTERCOMM SYSTEM * 
//* NOTE’ THE INTERCOMM PROC *LKEDT® LIAKEDITS MODULES FROM THE * 
44% SYSLIB CONCATENATION STREAM AS FOLLChS - * 
//* THE LOAD LIBRARY SPECIFIED BY THE C= PARAMETER? * 
4/* FCLLOwED BY MODULES FOUND IN FODUSR» FCOLIEs THEN MOCREL. * 
4/* THEREFORE» A PL/1 LOAD LIBRARY IS NEELED <- SEE PLIL16B. * 
//* TRE INTERCOMM LOAC MODULE IS PLACED ON IAT-MOCSCR. * 
4/* IT IS NOT NECESSARY TO RE-DO THE WHOLE LINK TO REPLACE 1 MCOULE * 
4/* IN TFIS CASE, ALL YOU SHOULD DO I1S2 * 
//* 1) REASSEMBLE OR RECOMPILE THE CHKANGED/AEb® MCCULE IATC A * 
4/* SEPARATE LOAD LIBRARY * 
4/* 2) OVERRIDE THE SYSLIN OD STMT TC //LKEDeSYSLIA OD * * 
4/* FOLLOW IT WITH INCLUDE CARDS * 
//* FOR THE MODULES YOL WISH TO REPLACE * 
‘/* 3) FOLLOW THOSE INCLUDES WITH THE FOLLChIAG 3 CARES! * 
4/* IACLUDE SYSLMOD(TESTICOM) * 
//* ENTRY PMYSTUP * 
4/* NAME TESTICOMIR) * 
//* 4) INSERT A OD STMT FOR THE LOAD LIBRARY ON WHICh THE * 
4/* REPLACEMENT MODULES RESIOE * 
4/* 5) CHANGE THE RESTART PARM ON THE JOB STATEMENT * 
4/* TO POINT TO THE LKEO STEP ° 
LL POOR OHO EH SEHEOE EEE SOOTHE EOE EOE E TEER OEE ESEEE EEE HOOTERS HH EST ERE RE EEEE ES 
//LKED EXEC LKEDTsLMOD=TESTICOMsQ=TESTs 

4/ PARMeLKED#@"LISToLETsXREFsNCALsSIZEs( 250K ,1COK) ° 


J/LKEDeSYSLIN DO DSN@=EEINCLITESTLINK) sDISP=(OLDyPASS) 
//PLILIB OD DSN@SYS1L-PLIBASE ,OISP=SHR PL/1 SLBRCUTINE LOAD LIBRARY 
//MOODREL OD DSN#=INTeMODREL sD ISP#®SHR 


Figure 61. Linkedit and Execution JCL for Test Mode (Page 2 of 3) 
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LAOS EEE OHEER EEE E ESHER EEE OO OEET ESET OOH OHDERESES ESTED HS TED ED EE TE DE 
44 EXECUTE INTERCOMM IN TESTMODE * 
LL AOSD AT EOE O OOOO HEHEHE EEE TESTES ETE OES OOH THEDNOEOTHDODOEEET ED ETE SED 
4160 EXEC PGM=TESTICOM,»PARM="TEST*,TIME=( 920) 

//STEPLIB DSN=INT.MODSCR »DISP=(OLDsPASS) (DYNLLIB) 

4/ DSN= INT.MODUSR »DISP=SHR (LSER LOAD LIBRARY) 

4/ DSN@=INT.MODLIBsDISP#=SHR (SYSTEM UPCATE LIBRARY) 
4 DSN= INT. MODREL sDISP=SHR (SYSTEM RELEASE LIBRAKY) 
4/ DSN=SYS1-PLIBASE,»DISP=SHR (PL/1 LCAC LIBRARY) 
//INTERLOG OD DSN@EEINTLOG»DISP=(NEWy)PASS) 5 

4/4 SPACE=(TRK9(1095) )sVOL=SER@=INTOO] UNIT#=SYSCA, 

4/7) DCB=(DSORG=PS pRECFM@VByBLKSIZE@4096 ,LRECL*94CS52,NCPmE yCPICC#C) 
//STSLOG DD SYSCUT#=A,DCB=(DSORG=PS yBLKSIZE#12C y»RECFM=FA) 

//SMLOG DD SYSCUT#A,DCB=(DSORG=PS  BLKSIZE=12C »RECFH2FA) 

J/SYSPRINT DD SYSCUT#A,DCB=(DSORG=PS,RECFR=VA,BLKSIZE #141 5LRECL#137) 
//RCTCOO DD DSN= INT.RCTCOO,DISP=SHR,y 

4/ DCB=(DSORG=DA,OPTCD=RF ) CUTPUT FORPFATS 

J/PRMIQUE DD DISP#OLDsDSN#INTcoPMIQUE, 

4/ DCB=(D0SORG=DA,OPTCD=R) SUBSYSTEM CISK CLEVE 
//STOKFILE OD DSN#=VSAMSD1.STCKFILE-CLUSTERsDISP#CLDy 

4/ AMP=(AMORG, ‘RECFM=F*) VSAM TEST FILE 
//PARTFILE DD DSN@ INTO TEST«PARTFILEsODISP=OLDy, 

4/ DCB=(DSURG=DA,OPTCO#R) BDAM TEST FILE 

4/0ESO000 DD DSN#INT.DESCOO,DISP=SHR, 

4 OCB={DSORG=DA,OPTCD=RE ) FILE CESCRIFTION RECCRCS 
JISYSIN DD DSN#=INT.«SYMTEST(TESTMSGS) sDISP#SEFy 

4 OCB=DSORG=PS TEST MCCE INKPLT MESSAGES 
//PRISTCP DUMMY 

J/1COMIN DUMMY 

//* 

J/STEPCAT DSN=VSAMSD1,D1SP=SHR VSAM CATALCG (CIF NEEDED) 
//CYNLPRNT SYSCUT#A 

//DYNLWORK UNIT#SYSDA,SPACE@( CYL, (151) ) 9DISP=(yPASS) 

//CYNLLIB DSN@ INT .MUDSCR»CISPH(CLDsPASS) 

4/* 

7/7 SNAPDD SYSCUTSA 

SISYSSNAP SYSCUT#A SNAP INPLT TEST FESSACES 
J/SYSSNAP2 SYSCUTBA SNAP CUTPLT TEST MESSACES 
//SYSUDUMP SYSCUT#A 

//PLIDUMP SYSCUT#A PL/1 "REPCRT® CUTPUT CIF LSED) 
4/* 

//ABNLIGNR DUMMY FORCE ABEND-AID TC IGNORE DUMP (PROCLCE 1B CLAP) 
4/* 

LOOSE EEO EO EOE ESSE EEE HOE FEO OOEE TEESE HOE EE EHH EEO ET TERETE DEERE TEDS 
44% PRINT INTERCOMM LOG FROM TEST MODE RUN * 
LAOH HOOEETHEH ESOS OSES ESET OTOH HE HOE TEESE HHT EHT TESTE HHT TESORO SORES TES 
//INTERLOG EXEC PCM=LOGPRINT »COND=EVEN 

//STEPLIB OD OSN#INT.MODREL »DISP=SHR 

J/SYSPRINT DD SYSOUT=A,DCB*(DSORG=PS »BLKSIZE=121) 

//INTERLOEG DD OSN@EGINTLOGsDISP#SHR»DCB=BLKSIZE=500C 

J/SYSIN OD OUMMY »,OCB=BLKSIZE=80 

4/ 
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Appendix A 


PL/1 JCL PROCEDURES 


The following JCL procedures are supplied on the Intercomm 
release library, SYMREL. Check with your System Manager before using 
them to ensure they reside on your installation’s system procedure 
library (SYS1.PROCLIB) and to verify parameters to code. For compile 
steps, SYSLIB references the SYMPL1 data set containing the members to 
be copied into PL/1 programs via “INCLUDE statements. Optional compile 
parameters may be added by coding PARM2=’,options’ on the EXEC 
statement, for example: 

// EXEC PLIX...,Q=...,NAME=...,PARM2=‘ ,MAP, LIST, STORAGE’ 


PLIXPC: PL/1 compile 
// EXEC PLIXPC,Q=TEST , NAME=PL1PROG 


PLIXPCL: PL/1 compile and linkedit for a resident program or 
dynamically loaded program which will be dynamically 
linkedited at Intercomm startup. NCAL is a_ required 
linkedit parameter. (The linkedit step, PARM override 
AMODE=31, RMODE=ANY causes the program to be loaded above 
the 16M line). 


// EXEC PLIXPCL,Q=TEST , NAME=PL1PROG , LMOD=PL1PROG 
// PARM.LKED='LIST,XREF,LET,NCAL,REUS , AMODE=31 , RMODE=ANY ' 


For dynamically loaded PL/1 subsystems add the following: 


//LKED.SYSIN DD * 
INCLUDE USRLIB(PLIV) 
INCLUDE USRLIBCINTLOAD) 
INCLUDE USRLIB(PLISHRE) (PL/1 V2 + Shared Library) 
ENTRY PLIV 
NAME program-name(R) 


For linkediting all PL/1 subroutines add the following: 


//LKED.SYSIN DD * 
ENTRY subroutine-name 
INCLUDE USRLIB(INTLOAD) (if dynamically loaded) 
INCLUDE USRLIB(PLISHRE) (PL/1 V2 - see below) 
NAME subroutine-name(R) 


Note that the INCLUDE statement for INILOAD may be omitted 
if the only external call is to PMIPLI. 


Figure A-1. Intercomm-supplied PL/1 JCL Procedures 
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Appendix A PL/1 JCL Procedures 


Refer to the Intercomm Operating Reference Manual for further 
details on JCL parameter requirements, and Intercomm linkedit with PL/1 
subsystems. Note that if PL/1 subsystems and subroutines are both 
included in the Intercomm load module, at least one PL/1 subsystem must 
be included before any PL/1l subroutines. IBMB... subroutines which may 
need to be included in the Intercomm load module can be determined from 
the program linkedit (unresolved external references; ignore WX (weak) 
references), or by using the ESD compile option. 


If using PL/1l Version 2 with a Shared Library, add an INCLUDE 
SYSLIB(PLISHRE) to the Intercomm Linkedit instead of including IBMB.... 


subroutines if resident PL/1l programs are used. Ensure the system 
library containing the PLISHRE module is concatenated after the 
Intercomm libraries for the SYSLIB DD statement. For dynamically 


loaded PL/1 programs, add an INCLUDE USRLIB(PLISHRE) just before the 
ENTRY PLIV and ensure the system library containing PLISHRE is 
concatenated after the Intercomm libraries for the USRLIB DD statement 
in PLIXPCL, or copy the module to MODLIB, or add a SYSLIB DD statement 
for the appropriate system library and include PLISHRE from SYSLIB 
instead of USRLIB. 
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Appendix B 


SOURCE STATEMENT LIBRARY COPY MEMBERS 


The following members in the Intercomm SYMREL source library 
contain source statement code which can be inserted in a PL/1l program 
simply by coding %INCLUDE member-name at the desired source line. 
SYMREL must be named in the DD statement concatenation for the SYSLIB 
data set for compilations (if Version 2 of the PL/1 compiler is used), 
or the members must be copied to a source library (SYMPL1) of the 
appropriate block size for the compiler. That source library must be 
defined for the SYSLIB data set in the compile JCL (SYMPL1 is the 
default in Intercomm supplied procedures JCL). 


NOTE: The block size of SYMREL is 6160 as released. 


Appendix B Source Statement Library 
Copy Members 


PLIENTRY 


The PLIENTRY member contains a DECLARE statement specifying Intercomm 
service routine names as ENTRY with OPTIONS (ASM INTER). 


DECLARE ( SELECT, 
RELEASE, 
READ, 
WRITE, 
GET, 

PUT, 
GETV, 
PUTV, 
RELEX, 
FEOV, 
COBPUT, 
ALLOCATE, 
ACCESS, 
MSGCOL, 
FESEND, 
FESENDC, 
COBSTORF, 
CONVERSE, 
LOGPUT, 
DBINT, 
PAGE, 
QBUILD, 
QOPEN, 
QREAD, 
QREADX, 
QWRITE, 
QWRITEX, 
QCLOSE, 
FECMDDQ, 
FECMFDBK, 
FECMRLSE, 
MAPIN, 
MAPOUT, 
MAPFREE, 
MAPEND, 
MAPURGE, 
MAPCLR, 
DWSSNAP, (Rel 10 only) 
INTSORTC, (Rel 10 only) 
INTSTORE, 
INTFETCH, 
INTUNSTO) ENTRY OPTIONS (ASM INTER); 
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Appendix B Source Statement Library 


Copy Members 
( PLMSGHD 


The PLMSGHD member contains level 5 declaration clauses naming 
and listing the attributes for all of the Intercomm message header 
fields. This member may be used in conjunction with a level 1 DECLARE 
statement to define a message structure. See Figure 17. 


MSGHLEN FIXED BIN(15) UNALIGNED, 

MSGHQPR CHAR (1), 

MSGHRSCH BIT (8) ALIGNED, 

MSGHRSC BIT (8) ALIGNED, 

MSGHSSC BIT (8) ALIGNED, 

MSGHMMN BIT (24) ALIGNED, 

MSGHDAT CHAR (6), 

MSGHTIM CHAR (8), 

MSGHTID CHAR (5), 

MSGHCON BIT (16) ALIGNED, 

MSGHFLGS CHAR (2), 

MSGHBMN BIT (24) ALIGNED, (MSGHADDR - Rel 9) 
MSGHSSCH BIT (8) ALIGNED, 

MSGHUSR CHAR (1), 

MSGHADDR BIT (16) ALIGNED, (MSGHBMN - Rel 9) 
MSGHLOG CHAR (1), 

MSGHBLK BIT (8) ALIGNED, 

MSGHVMI BIT (8) ALIGNED, 


5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
b) 
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Appendix B Source Statement Library 
Copy Members 


PLIHDR 


The PLIHDR member contains a BASED structure detailing the fields 
in the Intercomm message header, and can be used together with the 
address of the input message to reference individual header fields 
directly in the input message area. ADDRESS_OF_INPUT_MESSAGE must be 
declared as a pointer variable and initialized if necessary (see 
Chapter 3). 


DCL 1 MESSAGE_IN BASED (ADDRESS_OF_INPUT_MESSAGE), 

MSGHLEN FIXED BiN(15) UNALIGNED, 

MSGHQPR CHAR (1), 

MSGHRSCH_MSGHRSC BIT (16) ALIGNED, 

MSGHSSC BIT (8) ALIGNED, 

MSGHMMN BIT (24) ALIGNED, 

MSGHDAT CHAR (6), 

MSGHTIM CHAR (8), 

MSGHTID CHAR (5), 

MSGHCON BIT (16) ALIGNED, 

MSGHFLGS CHAR (2), 

MSGHBMN BIT (24) ALIGNED, (MSGHADDR - Rel 9) 
MSGHSSCH BIT (8) ALIGNED, 

MSGHUSR CHAR (1), 

MSGHADDR CHAR (2) ALIGNED, (MSGHBMN - Rel 9) 
MSGHLOG CHAR (1), 

MSGHBLK BIT (8) ALIGNED, 

MSGHVMI BIT (8) ALIGNED, 

MSGHEND /* USER FIELDS START HERE */, 


2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
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Appendix B 


PENTRY 


Source Statement Library 
Copy Members 


The PENTRY member declares and initializes static variables used 
in CALLs through PMIPL1 to the named Intercomm system service routines. 
See sample program using PMIPL1 CALLs in Appendix D. 


DCL 1 PENTRY STATIC, 


2 ( /*IF OFFSET ODD,TRUE OFFSET=- (OFFSET+1)*/ 


FIXED BIN(15); 


INTSORTC 
DWSSNAP 
MAPFREE 
FECMRLSE 
FESEND 
FESENDC 
ALLOCATE 
ACCESS 
MAPURGE 
MAPCLR 
MAPEND 
MAPOUT 
MAPIN 
INTUNSTO 
INTSTORE 
INTFETCH 
FECMFDBK 
FECMDDQ 
QWRITEX 
QREADX 
QWRITE 
QREAD 
QCLOSE 
QOPEN 
QBUILD 
SELECT 
RELEASE 
READ 
WRITE 
GET 

PUT 
RELEX 
FEOV 
COBPUT 
MSGCOL 
COBSTORF 
CONVERSE 
DBINT 
LOGPUT 
PAGE 
GETV 
PUTV 


INIT(99), 
INIT(95), 
INIT(91), 
INIT(87), 
INIT(83), 
INIT(79), 
INIT(75), 
INITCALY, 
INIT(67), 
INIT(63), 
INIT(59), 
INIT(55), 
INIT(51), 
INIT(47), 
INIT(43), 
INIT (39), 
INIT(35), 
INIT(31), 
INIT(27), 
INIT(23), 
INIT(19), 
INIT(15), 
INIT(11), 
INIT( 7), 
INIT( 3), 
INIT( 4), 
INIT( 8), 
INIT(12), 
INIT(16), 
INIT(20), 
INIT(24), 
INIT(28), 
INIT (32), 
INIT(68), 
INIT(72), 
INIT(76), 
INIT(80), 
INIT(84), 
INIT(88) , 
INIT(92), 
INIT(96), 


INIT(100) ) 
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(Rel 10 only) 
(Rel 10 only) 


Appendix C 


INTERCOMM TABLE SUMMARY 


Basic tables are included in the Intercomm release library 
(SYMREL) and must be modified (added to) for each installation. An 
asterisk (*) indicates optional tables which may be _ generated 
individually at each installation according to application program 
requirements. 


== SS SSS =< SS Se SS SS eq SS SS SS SS SS ES SS SS SSS 


TABLE or SYMREL and 
CSECT MODREL 
Name Description Created by Member Name 
BROADCST *Output Broadcast Table | BCGROUP macro PMIBROAD 
BTAMSCTS Front End Queue Table SYCTTBL macro BTAMSCTS 
(BTAM/TCAM/GFE only) 
BIVRBTB Front End Verb Table BIVERB macro BIVRBTB 
(User-name) | Front End Network LINEGRP, BLINE FENETWRK 
Configuration Table BTERM macros, etc. | (BTSAMP) 
VCT, LUNIT, (VTSAMP) 
LCOMP macros, etc. 
CHNGTB *Change Table for DC's None 
Change/Display Utilities 
File *File Descriptions Data FDHDR, FDETL None 
Description] Set (DESO00); generated macros 
Records by file load utility 


(DESnnnnn) PMIEXLD (for Change/ 
Display Utility) 
IXFDSCTn File Handler Data Set IXFDSCTA macro IXFDSCT1 
Control Table (50 DDs) 
IXFDSCT2 
(100 DDs) 
IXFDSCT3 
(200 DDs) 


Figure C-1. Table Names and Associated Macro Instructions (Page 1 of 2) 
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TABLE or SYMREL and 
CSECT™ MODREL 
Name Description Created by Member Name 
KEYTABLE *Display Utility Key DC's None 
Transformation Routing Table 

PADDTBLE *Edit Utility Pad Table PADD macro PADDTBLE 
PAGETBL *Page Facility Table PAGETBL macro PAGETBLE 
PMIALTRP *Output Utility Alternate PMIALTRN macro None 


Format Table 


PMIRCNTB *Output Utility Format Table| CSECT PMIRCNTB 


REPORT, LINE RPTnnnnn 
. ITEM macros 


PMIRPTAB *Output Utility Company/ DC's None 
Report/Terminal Table 

PMISTATB Back End Station Table STATION macro PMISTATB 

PTRNTBLE *Display Utility Symbol Edit] PATRN macro None 
Pattern Table 

REENTSBS Subroutine Entries List SUBMODS macro REENTSBS 

REPTAPE *Output Utility Batch Report| DC’s None 
Table 


SCT Subsystem Control Table SYCTTBL macro INTSCT 
(SCT) 
VERBTBL *Edit Control Table VERBGEN, VERB, PMIVERBS 
PARM, PMIELIN 
macros 


Figure C-1. Table Names and Associated Macro Instructions (Page 2 of 2) 
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oe ee =< SS ee ee Se ee 


Component Name Tables Used 
Change/Display Utility CHNGTB 
File Description Records 
KEYTABLE 
PMIFILET 
PTRNTBLE 
Edit Utility PADDTBLE 
PMIFILET 
PMIVERBS 
PMIDEVTB 
PMISTATB 
File Handler IXFDSCTn 
FAR statements 
Front/End TP Interface BTVRBTB 
Front End Network Table 
BTAMSCTS 


LOGCHARS 
PMIDEVTB 
PMISTATB 
User-coded Maps 
Monitor REENTSBS 
INTSPA 
INTSCT 
BROADCST 
Output Utility PMIALTRP 
PMIDEVTB 
PMIFILET 
PMIRCNTB 
PMIRPTAB 
PMISTATB 
REPTAPE 
RPTnnnnn (user-coded OFTs) 


Page Facility PAGETBL 


Figure C-2. Components and Associated Table Names 
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USING PMIPL1 


D.1 INTRODUCTION 


PMIPL1 was originally developed as an Intercomm service routine 
interface for PL/1 F compiled programs. Intercomm (and user) 
subroutines could not be defined as Assembler routines, and therefore 
the function of PMIPL1 was to convert the PL/1 F parameter list for a 
call to an Assembler routine to a standard Assembler parameter list. 
The PL/1 parameter list contained Dope Vectors for all non-arithmetic 


parameters (for character and bit strings). Under the Optimizer 
compiler, the Dope Vectors became Locator/Descriptors, but the basic 
structure (function) is the same. For calls to Assembler routines 


(Intercomm or user), PMIPL1 creates a new parameter list with the data 
field addresses from the Dope Vectors (Locator/Descriptors). For calls 
to user PL/1 subroutines, the original parameter list is copied and 
passed. All calls to Intercomm and user routines are made via PMIPL1 
which must be declared as follows: 


DCL PMIPL1 EXTERNAL ENTRY; 


All called subroutines (Intercomm and user) must be defined by SUBMODS 
macros in the REENTSBS table as discussed in Chapter 9. The subroutine 
to be called is given to PMIPL1 via the label of an index code into the 
REENTSBS table, declared as FIXED BIN(15) and passed as the first 
parameter on the call to PMIPLI1, as follows: 


CALL PMIPL1(routine-code-name,parml,...parmn) ; 


The SUBMODS definitions for commonly used Intercomm service routines 
are provided in the system release version of REENTSBS. Those for 
other routines and user subroutines have to be added at the end of the 
table. In addition, a copy member PENTRY (see Appendix B) is provided 
which gives the routine code names and index values for the Intercomm 
routines defined in the released REENTSBS. This member is to be copied 
into each program that uses the PMIPL1 interface via the following 
statement: 


%ZINCLUDE PENTRY; 


Labeled index codes for other subroutines may be added to PENTRY or 
declared separately, as described in Chapter 9. Note that the codes 
are absolute displacements (in increments of 4) to SUBMODS base 
definitions in the REENTSBS table. Once entries are added, they should 
never be deleted, new entries are always added at the end. This will 
ease maintenance of program code. 
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Under the Optimizing compiler, since Intercomm and user routines 
can be declared as ENTRY OPTIONS(ASM INTER) and thus will receive a 
standard Assembler parameter list for both arithmetic and character 
data fields, the use of the PMIPL1 interface is no longer necessary; 
direct calls can be made (see Chapter 3). Note, however, that when a 
pointer variable is passed as a parameter, the address of the pointer 
address is always passed no matter how the called routine is defined. 
Thus Optimizer PL/1 subroutines which receive only pointer variables 
and/or arithmetic fields as parameters can be declared as Assembler 
subroutines; the parameter list is the same. If character or bit 
strings are passed, Locators are generated and the Locator address is 
passed if the routine is declared as ENTRY EXTERNAL. For structures or 
arrays, set a pointer variable to the beginning of the area and pass 
that for easy definition of the area in the called routine. 


A sample program which combines the logic of the sample programs 
in Chapter 10, but uses PMIPL1 calls instead of direct calls, is given 
at the end of this Appendix. Note that this program is eligible for 
loading above the 16M line under Release 10 (all passed parameters in 
program’s DSA except the routine-code-names). Note also that 
fullword-aligned areas passed as character string variables to 
Intercomm routines require use of a DEFINED statement to reference 
subfields in the string (see FHCW and MCW). 


D.2 PMIPL1 PARAMETER LISTS 


For programs using PMIPL1 under the Optimizing compiler, all 
parameters passed on calls to PMIPL1 (except the routine-code-name) 
must be non-arithmetic or pointer variables if the called routine is 
Assembler, that is, Locator addresses for the parameters are passed to 
PMIPL1. When executing under XA or ESA and Release 10, PMIPL1 checks 
that each parm passed to the called subroutine is a 24-Amode address. 
PL/1 subroutines are defined on the SUBMODS macro in the REENTSBS table 
with the TYPE=PL1 parameter. COBOL subroutines should not be called by 
PL/1 programs, but if used, they are passed Assembler parameter lists 
by PMIPL1. COBOL subroutines that may be called by Assembler or PL/1 
programs must be defined on the SUBMODS macro with USAGE=REUSE or 
NONREUSE and may not call COBREENT. 


Exceptions to the non-arithmetic parameters for PMIPL1 calls for 
Intercomm service routines are as follows: 


MSGCOL - three parameters may be passed (instead of one parameter as 
described in Chapter 9) as follows: 


CALL PMIPL1(MSGCOL,message,SPA, return-code) ; 
where message is the same as in Chapter 9 
SPA is the SPA entry parameter 


return-code is declared as FIXED BIN(31) and may be the same 
field as the return-code entry parameter. 
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CONVERSE - the first parameter must be a fullword-aligned CHAR(4) 
field, and the second parameter must be a FIXED BIN(31) 
field as described in Chapter 8. 


PAGE - the second parameter (page-return-code) must be declared as 
FIXED BIN(31), see Page Facility. 


MAPIN - the six-parameter form of the call must be used, with the 
label of the input message area (structure), not the 
pointer, passed as the fourth parameter (see Message Mapping 
Utilities - MAPIN call formats). 


When using MMU, because the input message is mapped into the non-based 
symbolic map area in the program's DSA, a call to MAPFREE to free the 
area is not used. See Chapter 4 and compare sample programs in Chapter 
10 and this Appendix. 


Routines called via PMIPL1 (even if also via DYNLLOAD for 
dynamically loaded or PL1 subroutines) receive the caller's registers 2 
through 13, thus preserving the PL/1 environment for called PL/1 
subroutines. At entry to the called routine, register 14 points to a 
return address in PMIPL1 (or to return code in DYNLLOAD’s save area if 
entry is made via DYNLLOAD), register 15 contains the entry point 
address and register 1 points to the new parameter list set up by 
PMIPL1 in an Intercomm storage area acquired by PMIPLI. The 
routine-code parameter is not passed to the called routine. 


To set up the new parameter list, PMIPL1 acquires a 56-byte 
storage area for a 12-byte processing area followed by an 11l-word 
parameter list area (a larger area is acquired if more than 11 
parameters are to be passed). At entry to the called routine, register 
1 points to the 13th byte (4th word) in this area. The first 12 bytes 
are used as follows: 
bytes 1-2 - halfword length (in binary) of area 
3-4 - halfword routine-code value passed to PMIPLI1 
5-8 - fullword containing caller's original register 1 value 
(parameter list address) 

9-12 - fullword containing caller's original return address 
(register 14 at entry to PMIPL1 with hi-order byte (bit 
if 31-Amode address) cleared to binary zeros). 


On return to PMIPL1, the caller's original registers 1 and 14 are 
restored to the caller's save area before PMIPL1's parameter list 
storage area is freed. Register 15 in the caller's save area will 
contain a return code from the called Assembler routine if stored there 
by the called routine (or provided via RC parameter on RTNLINK macro), 
see Assembler Language Programmers Guide. On return from PMIPL1, the 
caller's registers 1 through 14 are restored and branch exit to its 
caller is effected via register 14 from PMIPLI1. 
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Using PMIPL1 


STMT LEV AT 


1 0 
2 1 90 
3 1 0 
4 1 0 
3 1 0 
6 1 0 
7 1 0 


7* TNQUIRE ON STOCK/PART FILES FCR MSG RESPONSE 


SQPL1: PROC CIN_MSG_PTRySPA_PTRsSCT_PTRoRC) 


CCL 


CCL 


CCL 


OcL 


CPTIONS(MAINsREENTRANT)§ 
DCLUIN_MSG_PTRy 


SPALPTR» 
SCT_PTR) POINTER; 


RC FIXED BIN(31)5 


PMIPL1 EXTERNAL ENTRY; 


1 MAP_NAMES STATIC+s 


3 IO_MAPGRCUP CHAR(8) 


LSING 


INPUT 
IAPUT 
INPUT 
INPUT 


/* CEFINE PMIPLI 


PMIPLI 


PARK 
PARP 
PARM 
PARP 


fwne 


EATRY 


e/ 


*/ 
¢/ 
¢/ 
o/ 


o/ 


/* CECLARE STATIC STCRAGE AREAS ¢#/ 


3 1OLMAP CHAR(Gd INITCOMAPLT DE, 
3 ERROR_MAP CHAR( Bd INITCTERRPAPS); 


1 FILENAMES STATIC» 
3 DD STCCK ChAR(8) 
3 DO_PART ChAR(8) 


INITC'STKSTAT') 9 


/* FOR CALLS TO BRU @/ 


7* FOR CALLS TO THE FILE FANCLER */ 


INITOC'STCKFILE')» 
INITC'PARTFILE')5 


ZINCLUDE PENTRYjfe eee eee ee ese renee SSE He ECE eH SHEE EHH HERE ES ESS ES HENE 
OCL 1 PENTRY STATIC, 
2 ( SIF OFFSET OCCe+TRLE OFFSET@#-(CFFSET+¢1)%/ 


INTSORTC 
OWSSNAP 
MAPFREE 
FECPRLSE 
FESEND 
FESENDC 
ALLOCATE 
ACCESS 
MAPURGE 
MAPCLR 
MAPENDO 
MAPOUT 
MAPIN 
INTUNSTO 
INTSTORE 
INTFETCE 
FECMFOBK 
FECMODQ 
QWRITEX 
QREADX 
QWRITE 


INIT(GSG),» 
INITUGE Dy 
INIT(G1)>» 
INIT(ET7)» 
INIT(83)>5 
INITO7G)» 
INIT(75) » 
IALTOZ1DS 
INITCET)» 
INITCE3)» 
INITASS) 
INITUS5S)» 
INITCS1)» 
INITUS7)5 
INIT(4&2 D5 
INIT(35) 5 
IN1T(35)5 
INIT(31) >» 
INIT(27) 9 
INIT(23)5 
INITCIUS) 5 


je 


/*# 
/¢ 


UPCATE %/ 


REL 10 */ 
REL 160 */ 


Figure D-1l. 
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Appendix D Using PMIPL1 


STWT LEV AT 


QREAD INIT(15), 
QCLOSE INITOAlL)» 


QOPEN INITO 2)5 
QBUILD INITC 3)5 
SELECT INITO 4)5 
RELEASE INIT( Bd, 
READ INIT(12)5 
WRITE IN1T(16)5 
GET INIT(2C)» 
PUT INIT(24),5 
RELEX INIT(26) 5 
FEOV INIT(32)5 
COBPLT INIT(68)5 
MSGCOL INIT(72)5 
COBSTORF INITC7E)» 
CONVERSE INIT(8C), 
DBINT INIT(84) 5 
LOGPUT INIT(86), 
PAGE INIT(G2)5 
GETY INIT(SE), 
PUTV INIT(1CO) ) 
FIXED BIN(15);5 
bs dadndiadiadtadetadatntnadainiad /* FOR PMIPL1i CALLS TO ICCP AND USER RCUTINES */ 


Figure D-1. Sample PL/1 Program Calling PMIPL1 (Page 2 of 15) 
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STMT LEV AT 


ZINCLUGE PLILOGCHj PF e Fee ere reser eee oeoe reese eo eH HHO OF OD ET HOO OO EOE OOOS 
DECLARE LAN CKAR(1) STATIC IAITO® "95 
CECLARE UANPCT CHAR(L) STATIC INITC® 
CECLARE UANSEL CHAR(1) STATIC IAITC! 
DECLARE GANMOSEL CHAR(1L) STATIC IAITI® "95 
OECLARE VAHSEL CHAR(1) STATIC INITI* "95 
CECLARE UAHFCSEL CHAR(1) STATIC INITIO "95 
CECLARE VAX CFAR(1) STATIC INITO® "95 
DECLARE VAXMDOT CHAR(1) STATIC INIT(® "03 
DECLARE UNN ChAR(1) STATIC IAITOS 95 
CECLARE UNNPCT CHAR(1) STATIC IAITC "D5 
CECLARE UNNSEL CHAR(1) STATIC INIT’ "D5 
DECLARE UNNMOSEL CHAR(1) STATIC IAIT(" ! 
CECLARE UNHSEL ChHAR(1L) STATIC IMSITU® "D5 
CECLARE UNHPCSEL CHAKI1) STATIC IAITO® 95 
DECLARE UNX CFrARI1) STATIC INITC® "05 
OECLARE UNXMDT CHAR(C1) STATIC INITC® 995 
DECLARE PAN CHAR(1) STATIC INITOS 9); 
CECLARE PANPCT CRAR(1) STATIC INIT(® ° 
DECLARE PANSEL CHAR(1) STATIC IAIT(S ° 
DECLARE PANMOSEL CHARI1) STATIC INIT(' 
a 
) 


5 
> 
"5 
DECLARE PAHSEL CHAR(1) STATIC INITC? 
DECLARE PAHMDSEL CHAR(L) STATIC IAITC 
DECLARE PAX CHAR(1) STATIC INITO® "05 
DECLARE PAXMCT CHAR(1) STATIC IAITC' "D3 
DECLARE PSN CKAR(1) STATIC INITO® "D5 
DECLARE PSNFDT CHAR(L) STATIC IKITC' "35 
CECLARE PSNSEL ChHAR(1) STATIC INITO® "95 
DECLARE PSNMDSEL CHAR(1) STATIC INITC! ! 
DECLARE PSHSEL CHAR(1) STATIC IBIT(® "95 
CECLARE PSHMOSEL CHAR(1) STATIC INITC(® "D3 
CECLARE PSX CFAR(1) STATIC INITO' "D5 
DECLARE PSXMCT CHAR(1) STATIC INIT(® "D3 
DECLARE SUPR CHAR(1) STATIC INIT(® "95 
OECLARE WRITEL CHAR(L) STATIC INIT(S ')3 
CECLARE ERASwWRIT CHAR(1) STATIC IAIT(' 
DECLARE ERASWRAL CFAR(1) STATIC INIT( 
DECLARE RMDT CHAR(1) STATIC INITC® "93 
DECLARE RKEYBD CHAR(1) STATIC IAITC(® ¢ 
DECLARE RMOTKEYB CHAR(1) STATIC INIT(? 
CECLARE ALARM CHAR(1) STATIC IAITC® "95 
CECLARE ALRPRHOT CHAR(1) STATIC IAIT(! 
CDECLARE ALRMRKEY CHAR(1) STATIC IAIT(? 
DECLARE ALRMRMKY ChAR(1) STATIC IANIT(! 
DECLARE PRNTNL CHAK(1) STATIC IAIT(® ! 
DECLARE PRNT4O CHAR(1) STATIC IAITC® * 
DECLARE PRNT64 CHAR(1) STATIC IKITC® ! 
‘ 
t] 


DECLARE PRNT8O CHAR(1) STATIC IAIT(* 
DECLARE PRNLRAMOT CHAR(1) STATIC INIT 


CEOKCDDGDDDFDDCGODDFDOGOODOO OOOO OAO OOO OOO OO AO OOOO O OOO oOO Oooo 


1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 


Figure D-1. Sample PL/1 Program Calling PMIPL1 (Page 3 of 15) 


4 


214 


Appendix D 


STMT LEV WT 


CECLARE 
DECLARE 
DECLARE 
DECLARE 
CECLARE 
CECLARE 
CECLARE 
DECLARE 
DECLARE 
CECLARE 
CECLARE 
DECLARE 
DECLARE 
CECLARE 
DECLARE 
DECLARE 
DECLARE 
DECLARE 
CECLARE 
DECLARE 
DECLARE 
CECLARE 
DECLARE 
DECLARE 
DECLARE 
CECLARE 
DECLARE 
OECLARE 
DECLARE 
DECLARE 
CECLARE 
DECLARE 


oho Mo No NE -R-N-MoNeM-oMoRoRoMoRoRoMoBoeoRon-—oMoeoRokaoRagaReoke) 


1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 
1 


Figure D-1. 


PR4ORMDT CHAR(1) 
PRO4KMCT CrAR(1) 
PREORMDT CHAR(1) 
PRNLRKEY CHAR(1) 
PRACRKEY CHARI1) 
PRO4ARKEY CHAR(1) 
PRBORKEY CHAR(1) 
PRNLRMKY CHAR(1) 
PR4CRMKY CHAR(1) 
PRO4AREKY CraAR(1) 
PREORMKY CrAR(1) 
PRNLALRM CRAR(1) 
PR4CALRM CHARI1) 
PRO4ALRA ChAR(1) 
PREOALRM CFAR(1) 
PRNLARMD CrAR(1) 
PR4CARMD CHAR(1) 
PRO4ARMD CHAR(1) 
PRBOARMD ChAR(1) 
PRNLARKY CFARI1) 
PR4OARKY CHAR(1) 
PR64SARKY CHAR(1) 
PRUOARKY CFAR(1) 
PRNLAMKY CRAR(1) 
PR4CAMKY CRAR(1) 
PRO4SARKY CRAR(1) 
PREBOAMKY ChAR(1) 


STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 
STATIC 


INITC! 
INITC! 
InITC' 
IKITC' 
IKITC' 
INITC' 
IAIT(' 
InITOC! 
INITC! 
IKITC' 
IAITC' 
IKNITC' 
IhITC! 
InITC' 
IAITC' 
INIT(' 
INIT¢! 
IKITC! 
IhIT¢' 
INIT! 
INITC! 
INITC! 
INITC' 
INIT(! 
INiT(! 
IhKITC' 
INITC' 


KRULL CHAR(1) STATIC IIT" "D5 
NL CRAR(1) STATIC INIT(E , 
FF CFAR(1) STATIC INITCE 
CR ChAR(1) STATIC INITC® 


SI CHAR(1) STATIC IKITC(® 
SORTK SHOES EHO E TEED 


i@ 


oe we HO HP we We we we we Oe ee we we me HH HO we wn WO we we we we we 


oe 
woe 


Using PMIPL1 


Sample PL/1 Program Calling PMIPL1 (Page 4 of 15) 
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STMT LEY NT 


7* DECLARE EXTERNAL STORAGE AREA ¢/ 


68 1 O (CCL 1 IN_MSG BASECCUIN_MSG_PTR) 5 
3 IN_LHCR» . 

ZINCLUDE PLMSGHD; OOF eee tee es eH OOee EHO dane HEH HEH HEHEHE EHEHEHEEeenees 
MSGRLEN FIXEO BIN(15) UNALIGNEDs 
PSGRCPR CFAR (1), 
MSGFRSCH BIT (8) ALIGNEDs 
MSGFRSC BIT (8) ALIGNED, 
MSGrSSC BIT (8) ALIGAEC, 
MSGFMAN BIT (24) ALICNEOs 
PSGFDAT CrAR (6)5 
FSGRTIM CFAR (8)5 
MSGRTIO CRAR (5), 
MSGFCON BIT (16) ALIGNEO, 
MSGFFLGS CFAR (2), 
VSGFBMN BIT (24) ALIGNED, 
MSGHSSCk BIT (8) ALIGNECs 
MSGRUSR CrAR (1), 
MSGrADDR BIT (16) ALIGNED, 
MSGFLUG CKAR (1)5 
MSGRBLK BIT (8) ALIGNEC, 
MSGHYMI BIT 18) ALIGNED, 


5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 
5 


Ooo eeeeereeeerees 
3 INLTEXT; 7* RCT REFERENCED */ 


/* INPUT WILL BE REFERENCED 8Y THE FIELD NAMES CF THE SYMBOLIC maAP 


Figure D-1. Sample PL/1 Program Calling PMIPL1 (Page 5 of 15) 
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STMT LEV AT 


/* DECLARE AUTOMATIC STORAGE AREAS *%/ 
LINCLUDE STKSTATE js RP ee ee reer ee eee teense ee eee ROPE REESE ODES ORE EHEE DEES 
DCL 1 MAP UNALIGNEDs 
3 VERBFs 
4 VERBL FIXED BIN(15)5 /* LENGTH */ 
4 VERBT CHAR( 1)» /* TAG */ 
4 VERB CHAR(4) 5 
2 PARTNOF» 7* START STRUCTURED SEGPEAT */ 
3 PARTNOL FIXED BIN(15)5 /* LENGTH */ 
3 PARTNOT CHAR(1)5 /* TAG */ 
3 PARTNO, 
4 FILLER PIC "(4119's 
4 RBNBYTE PIC '9',y 
USEG1 >» 
3 WHSNOF, 
4 wkSNOL FIXED BIK(15)5 /* LENGTH 
4 WHSNCT CHAR(1)5 /* TAG ¥/ 
4 wHSNO PIC "999", 
PRTDATAF >» 
4 PRIDATAL FIXED BIN(15)5 /* LENGTH 
4 PRIDATAT CHAR(1)5 /* TAG */ 
4 PRTIDATA CHAR(54), 
ORDUNTF, 
4 OQRDUNTL FIXED BIKN15)5 /* LENGTH 
4 OROUNTT CHAR(1),5 /* TAC */ 
4 OROUNT CHAR(5), 
PRTIPRCF 9 
4 PRTPRCL FIXED BIK(15)5 /* LENGTH 
4 PRIPRCT CHAR(1), /* TAG */ 
4 PRTPRC FIXED DEC(754)5 
wHESLOCFs 
4 wHSLOCL FIXEO BIN(15)5 /* LENGTH 
4 WHSLCCT CHAR(1)5 /* TAC ¥/ 
4 WHSLOC CHAR(23)5 
STKLEVF 5 
4 STKLEVL FIXED BIN(15)5 /* LENGTH 
4 STKLEVT CHAR(1),5 /* TAG */ 
4 STKLEV FIXED DECtI7)>s 
LEVDATEF, 
4 LEVDATEL FIXED BIKN(15)5 /* LENGTH 
4 LEVDATET CHAR(1), /* TAG *#/ 
4 LEVDATE CHAR(6) >» 
STKORDF» 
4 STKOROL FIXED BINI15)5 /* LENGTH 
4 STKOROT CHAR(1)5 /* TAG #/ 
4 STKORD FIXED DEC(7)» 
ORDDATEF» 
4 ORDDATEL FIXED BIK(I5), /* LENGTH 
4 ORDDATET CHAR(1), /* TAG *#/ 


Figure D-1l. Sample PL/1 Program Calling PMIPL1 (Page 6 of 15) 
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STFT LEV AT 


4 CRODATE CHAR(8), 
2 FILLER CHAR(1); 7* END GF PAP *%/ 
90 1 #0 DCL 1 ERRMAP UNALIGNED, 
3 ERRASGF, 
4 ERRMSGL FIXED BIN(15)5 /* LENGTH #*/ 
4 ERRMSGT CHAR{1), /* TAG #/ 
4 ERRMSG CHARI5O) 5 


2 FILLER ChHAR(1); /* ENO CF MAP *#/ 
Pee PPR EEL CC ercrry yy 7* ACA-BASEC SYMBOLIC MAP AREAS #/ 
91 1 OQ CCL 1 MMU_LAREAS ALIGNED, 7* BPBU CONTROL AREAS #/ 
3 MMULCUMMY FIXED BIN(31)¢ 
3 °=MCB CHAR (4E) 


3 MCW LNALIGNED CHAR(4)y 
1 MCWLREDEF GEF MML_AREAS oP Cry 
5 MCW1] CHAR( 1)» 
5 MCw2 CHAR(1), 
5 MCh3 CHAR( 1), 
5 MCw4 CHAR(1); 


92 1 0 (CCL 1 FHLAREAS ALIGNED, /* FILE PANCLER CONTROL AREAS ¢/ 
3 FHLDUMMY FIXED BIN(31),9 
3 EXTOSCT CHAR(4E)y 
3 FHCW UNALIGNED CHAR( 4), 
1 FHCWLREDEF DEF FH_AREAS.FRCh, 
> FhCWL CHAR(1}¢ 
5 FHCw2 CHAR(I1), 
5 FRKCW3 CHAR(1), 
5 FHCW4 CrAR(1); 


Figure D-1l. Sample PL/1 Program Calling PMIPL1 (Page 7 of 15) 
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STMT LEV KT 


93 PART_RECORD, 7* 100 BYTE BCAM RECORD WITHOUT KEYS 9/ 
3 P_REC_PAKT_DATAy 
5 PLREC_PIN PIC'(5)9", 
5 P_REC_DES CHAR(54)4 
5 P_REC_UNT CHAR(5)» 
3 P_LREC_PRC FIXED CECIMAL(794)» 
3 P_LREC_LMFR_NUM CFAR(15)» 
3 P_LREC_FILLER CHAR(17)3 


STOCK RECORD, 80 BYTE VSAM RECORC */ 
3 DELETE_CHAR CHAR(1)>» 


3 S_REC_KEY_FIELD» 

5 S_REC_WHS PIC'(3)G"%y 

5 S_REC_PNO PIC*(5)9%, 

S_REC_FILLER CHAR(28)5 

S_REC_STOCK_DATAs 
S_REC_WLC CHAR(23)5 
S_REC_LEY FIXED DECIMALI7)>5 
S_REC_LDT CHAR(6)» 
S_REC_URD FIXED DECIPAL(7)» 
S_REC_GDT CHAR(6); 


DATE» /* DATE EDITING */ 
MONTH CHAR(2)5 


SLASF1 CHAR(1)5 
DAY CRAR(2)5 
SLASH2 CKAR(1)»5 
YEAR CHAR(2)5 


CURRENT_FILE CHAR(8) 3 /* CCATAINS FILE NAME TC BE ACCESSED */ 
ERROR_FLAG FIXED DECIMAL(1) INIT(C)§ /* ERROR FLAG */ 

RBN CHAR(3)5 /* 2 BYTE REN FCR BOEM READ ¥/ 

RBNWORD FIXED BIN(31)5 FIELD FOR RBN CONVERSICN ¥/ 
KEY_FIELD CHAR(8)$ hKILL COKTAIN VSAM KEY */ 

MAP_GROLP_A CHAR(8)3 hILL CONTAIN MAFGROUP KAME */ 

MAP_A CHAR(8);3 whILL CONTAIN PAF NAME */ 

ERROR_MAP_A CHAR(8); hKILL COKTAIN ERRCR MAP NAME 9/ 

TIO CHAR(5)3 TERMINAL ID FCR CALLS TO MMU ¥/ 


ee oe ll oe ll ol 
ooooooo0o°”e 


Figure D-1. Sample PL/1 Program Calling PMIPL1 (Page 8 of 15) 
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| STPRT LEV NT 


105 
106 
107 
108 
109 
110 
111 


112 
113 
114 


115 
116 
117 
118 


128 
129 


ee 


om 


me NA PO 


mA 


Using PMIPLIL 


MAINLINES OG3 


RC = 03 7* INIT TRE INTERCGMM RETURN COGE */ 
TID © MSGHTID; 7* SAVE TERMINAL=ID FOR MMU CALLS #/ 
STRING(MCW) «= ° ‘; ¢@ INIT PAP CONTRCL WORD */ 
MAP_GROLP_A = IG_MAPGROLP; /* INIT KAP GROUP NAME #/ 
MAP_A = [0_KAP; /* INIT MAP KARE o/ 
ERROR_MAP_A = ERROR_MAP} /* INIT ERRCR MAP NAME #/ 
CALL PMIPLIC(HAPINSMCByMAP_GRCUP_AsMAP_AsIN_MSGyMCWHMAPLD| 
UNSPEC(VERB) = °'B; /* NO VERB IK TRE CLIPUT MESSAGE */ 
IF UNSPEC(PARTNCT) «= ''B } UNSPEC(RASNCT) a= ''8 
THEN /* INVALIC INPUT #/ 

DO; 


ERROR_FLAG = 1} 
LEAVE MAINLINE} 
END} 
ELSE 
IF HCW1 a= ‘O08 
THEN /* PAPIN ERRCR */ 
DQ; 
ERROR_FLAG = 2} 
LEAVE MAINLINE} 
ENO} 
STRING(MCW) = * = A'5 /* CLEAR FLAG/ATTRIBUTE BYTES */ 


CALL PMIPL1(HAPCLR»MCKyMAP_GROUP_AyPAP_AyMAPLeTIC)3 


CALL SDAM_READ; 


IF ERROR_FLAG aw 3 /* IF FILE SELECTED, RELEASE IT ¢/ 
THEN 
00; 
STRING(FECh) = ! "3; /* INIT FrCw FOR CALL TO RELEASE */ 


CALL PMIPLI(RELEASEVEXTCSCT»FECW)3 /* ALWAYS RLSE THE FILE */ 


END; 
IF ERROR_FLAG as 0 /* BOAM REAC RCUTINE FAIL 2? #/ 
THEN LEAVE MAINLINE; /* YES, LEAVE THE MAIN LIKE 9/ 


Figure D-1. Sample PL/1 Program Calling PMIPL1 (Page 9 of 15) 
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Appendix D Using PMIPL1 


STMT LEV AT 


130 CALL VSAM_READ; 


IF ERROR_FLAG a= 3 /* IF FILE SELECTEDs RELEASE IT ¥/ 
THEN 
DO; 
STRING(FRCW) = "5 /* INIT FRCw FOR CALL TO RELEASE */ 


CALL PMIPLI(RELEASESEXTCSCTsFRCW)§ /#* ALWAYS RLSE THE FILE */ 
END; 
IF ERRCR FLAG a= 0 7* WSAM READ RCUTINE FAIL ? ¥/ 
THEN LEAVE MAINLINE; 7* YES» LEAVE TREE PAIN LINE ¥*/ 


/* ALL FILE 1/0 1S COPPLETEs SEND AN CLIPLT MESSACE 9%/ 
STRING(MCW) = ? 3 /* INIT MAP CONTROL WORD */ 


CALL PMIPLI(MAPOUTsPCByMAP_GRCUP_AgsPAP_AygMAPLyMChsTIC)§ 


IF MCWl a= 'Q! /* WAPCLT FAIL 2 */ 
THEN /* YES */ 
DO; 
ERRCR_LFLAG = 2; 
LEAVE MAINLINE; 
END; 
STRING(MCH) = * QQ 4; /* PAPENOD WILL QO THE QUTPLT MESSAGE */ 


CALL PMIPLI(MAPENDsFCBsMAPLsMCW); /* DUMMY SECOND PARAMETER */ 


IF MCW1 a= ‘8! /* MAPEND FAIL ? ¢/ 
THEN 7* YES #/ 
DO} 
ERROR_FLAG = 2; 


CALL PMIPLI(MAPURGEs PCB) 5 
LEAVE MAINLINE; 


END; 
END MAINLINE; 


Figure D-1. Sample PL/1 Program Calling PMIPL1 (Page 10 of 15) 
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Appendix D 


STMT LEY AT 
150 1 0 
151 11 
152 11 
153 1 2 
154 1 2 
155 1 2 
156 1 1 
157 1 2 
158 1 2 
159 1 ou 
160 1 2 
161 1 2 
162 1 2 
163 11 
164 1 2 
165 1 2 
166 1 2 
167 lou 
168 1 2 
169 1 2 
170 1 2 
171 11 
172 1 0 


Figure D-l. 


Using PMIPL1 


SELECT (ERROR_FL&AG)5 


WEEN (015 /* OK, AC ACTICKR */ 
WREN (1) /* INVALID INPUT *%/ 
CO; 


ERRMSG @ "INVALIC CATAt PARTAC & wHSNC MUST BE AUFERIC'S 
CALL SENC_LERR_MSG3 /* SENC TRE ERRCR FESSAGE */ 


END; 
WEEN (2) /* MAU FAILURE *¢/ 
OG; 
RC = 123 /* INTERCCPPR SENCS AK ERROR FESSAGES/ 
END; 
WREN (3) /* ND CO %/ 
0a3 
ERRMSG = "NO COCARD FCR FILE SELECTEC'; 
CALL SEND_LERR_MSGs /® SENC TKE ERRGR FPESSAGE #/ 
END; 
WhEN (4) /* 10 ERRCR #/ 
00; 
ERRMSG © 'J/Q ERRCR CURING FILE ACCESS, TRY AGAIN 
CALL SENOLERR_MSG3 /* SEND TRE ERRCR MESSAGE */ 


END; 
WHEN (5) /* RECCRC ACT FCUND */ 


00; 
ERRMSG = "RECORD ACT FOUNC'; 
CALL SEROLERR_MSG; /*® SEND THE ERROR MESSAGE #/ 


ENC; 


END; 


RETURN; 


Sample PL/1 Program Calling PMIPL1 (Page 11 of 15) 
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Appendix D Using PMIPL1 


STAT LEV AT 


173 BDAM_READ?: PROC; /* READ BDAM FILE BY RBN */ 

174 RBNWORD = RBNBYTE; /* CONVERT CIGIT TO BINARY */ 

175 UNSPEC(RBN) |= SLUBSTRCUNSPEC(RBNWORD)59924)5 /* MUST BE 3 BYTES */ 
176 CURRENT_LFILE = DD_PART3 /* FILE TG GE ACCESSED ¥/ 

177 STRING(FHCW) = ° 5 /*@ INIT FILE FANDLER CCNTROL WORD */ 
178 UNSPEC(EXTDSCT) = *"B; /* INIT FILE FANDLER CONTROL BLOCK */ 


179 CALL PMIPLIC(SELECT,EXTCSCTsFrCwsCLRREAT_FILE)§ /* SELECT FILE *%/ 


180 IF FHChl = ‘9° /* SELECT ERROR 75 NO CD */ 
THEN 


dO; 
ERROR_FLAG = 3; 
RETURNS 
END} 
STRING(FKCWK) = ¢ 5 7* SELECT OKs INIT FHCR FOR READ*/ 


CALL PMIPLICREADsSEXTDSCTsFFCh»PART_RECURC»RBN)§ /* BDAM RD BY REN @/ 


SELECT(FHCW1); /* CHECK READ RETURN CODE *#/ 
WHEN('O'); /* OKs DC NOCTHIAG */ 
WHEN("1*) /* 1/0 ERRCR *#/ 

DO; 
ERROR_FLAG = 4; 


NNN 
MPN NN 


WHEN(*2") RECCRCE NCT FOUND */ 
DO; 
ERROR_FLAG = 5; 
RETURN; 
END; 
WHEN('9') SELECT FAILED */ 
DO; 
ERROR_FLAG = 3; 
RETURN} 
END} 
OTHERWISE; 
END} 
IF STRING(P_REC_PIN) a= STRINGC(PARTAC) /* RECORD PART#GIVEN PART? */ 
THEN 7* NC» PART AGT FOUND 9/ 
DO; 
ERROR_FLAG = 53 
RETURN} 
END} 
PRIDATA = P_REC_DES; PART DESCRIPTICN TO I/O MAP #/ 
ORDUNT © P_REC_UNT} UNITS TC 1/0 MAP */ 
PRTPRC = P_REC_PRC} PART PRICE TO I/C MAP 9/ 
END BDAM_READ; 


NNN 
MeN N ND 


NNANNN ND 
Orrnnn 


NNNN NNN 
ooo0oorrr 


Figure D-1l. Sample PL/1 Program Calling PMIPL1 (Page 12 of 15) 
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Appendix D Using PMIPL1 


STMT LEV NT 


210 VSAM_READ: PRCC; READ WSAP FILE BY KEY */ 

211 UNSPECCEXTOSCT) = ''B5 INIT ExXTCSCT */ 

212 STRING(FHCh) = ! at INIT FRCW 9/ 

213 CURRENT_FILE = DO_STOCK; FILE TO BE SELECTED */ 

214 SLRECLWHS = wHSNO; bHSNG IS PART OF THE KEY #/ 

215 STRINGCS_REC_PNO) = STRING(PARTAC); /* PARTAC IS PART CF THE KEY */ 
216 KEYLFIELD = STRING(S_REC_KEY_FIELD); /* THE wWS#M KEY */ 


217 CALL PMIPLI(SELECT,EXTCSCTsFHCh,CLRRENT_FILE)$ /* SELECT VSAM FILE *%/ 


218 IF FHCwl = '9! 7* SELECT FAIL 7 #/ 
THEN 74 YES ¢/ 
00; 
ERROR_FLAG = 3; 
RETURN; 
END; 
STRING(FHCRK) = ° 5 /@ INIT FRCW FCR READ #/ 


CALL PMIPLI(GETV,EXTOSCTsFRCWsSTOCK_RECCROE sKEY_FIELO)3/® RO BY KEY */ 


SELECTCFHCw1); /* CRECK CETVY RETURN COCE #/ 
WHEN('1") 7* 1/0 ERROR */ 
0C; 
ERRCR_FLAG = 4; 
RETURN; 
ENO; 
wHEN(*2°) 7* RECCRG NOT FCUND @/ 
DG; 
ERROR_FLAG © 5; 
RETURN; 
ENO; 
WHEN('9') INVWALIC REQUEST *%/ 
00; 
ERRCR_LFLAG = 3; 
RETURN; 
END; 


Figure D-1. Sample PL/1 Program Calling PMIPL1 (Page 13 of 15) 
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Appendix D Using PMIPL1 


STMT LEV AT 


237 


N 
_ 


WHEN('O*") /* SLUCCESSFLL ACCESS */ 
DO; 7* RECCRO FIELCS TC 1/0 MAP ¥/ 
WHSLOC = S_REC_wRLC3 
STKLEV = S_REC_LEV; 
MONTH = SUBSTROIS_REC LOT) 5192)5 
DAY = SUBSTRUCS_REC _LOT}5392)5 
YEAR = SUBSTRCUS_REC LET) 95592)3 
SLASH1», SLASH2 =» '/';3 
LEVDATE = STRING(DATE); 
STKORD = S_REC_CRD; 
MONTH #@ SUBSTR(USLREC_COT)s192)5 
DAY = SUBSTRICS_REC_CCOT)}5392)3 
YEAR = SUBSTRI(S_RECL COT} «59233 
ORODATE = STRING(DATE); 
END; 
END; /*¢ END CF GETV PRCCESSING *#/ 
END VS AM_READ; 


239 
240 
241 
242 
243 
244 
245 
246 
247 
248 
249 
250 
251 


2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 
2 


OF NNN NNN NN ANN 


Figure D-1. Sample PL/1 Program Calling PMIPL1 (Page 14 of 15) 
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STAT 


253 
254 
255 
256 
257 


2538 
259 


LEW 


Figure 


Using PMIPL1 


SEND_ERR_MSG: PROC; 
STRING(MCH) = 5 /* INIT MAP CCNTRCL WORD ¢/ 
UNSPEC(MCB) = "3; /* CLEAR PAP CCATRCL BLOCK */ 
je MAP THE ERROR FESSACE */ 


CALL PMIPLI(MAPOUT,MCBsMAP_GRCLP_A,ERRCR_MAP_AVERRMAP MCW, TIC); 


IF MCwl = *0! /® SUCCESSFLL MAPOUT 2 &/ 
THEN /* YES */ 
003 
STRING(RCW) = * QQ 8% 7¢ G CPTICN FCR MAPEND #/ 
MCw3 = RRITELS /® NOT EKASE=WRITE #/ 


CALL PMIPLI(MAPENDs PCB eMAPlLoMCRk)5 /* SEND THE MAPPED MESSAGE */ 
IF MCwl a= 8! /@ MESSACE CLEVED CK ? ¢/ 
THEN /@ nC es 

003 


CALL PMIPLICMAPLRGEsPCB)§ /* PLRGE MMU WORK AREA @/ 


RC = 12; /@ INTERCCHH SENCS AN ERROR MESSAGE @/ 
END; 
END; 
ELSE 
RC # 12; /* MAPOLT FAILED, I1C SENDS A MESSAGE ¢/ 
ENO SENDLERR_ASG; 


END SQPL1; 


D-1. Sample PL/1 Program Calling PMIPL1 (Page 15 of 15) 
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APPENDIX E 


SAMPLE PL/1 SUBROUTINE INTERFACE PROGRAM 


E.1 INTRODUCTION 


The routine listed below can be used to interface a PL/1 program 
to a user subroutine when either is dynamically loadable. Declare it 
in the calling PL/1l program as ENTRY EXTERNAL for calling PL/1 
subroutines. The called subroutine must be defined to the REENTSBS 
table via a SUBMODS macro coded with the LNAME parameter in USRSUBS. 
On the PL/1 program call to BINTFAC, the first parameter must be the 
label of the 8-character (low-order blank padding, if needed) name 
(same as for LNAME parameter) of the desired subroutine (name in DSA if 
caller is loaded), the other parms (if any) are passed on to the 
subroutine. To use this routine, include it in the Intercomm linkedit 
for resident callers, link it with caller when calling program is 
loaded. Note that this routine preserves the PL/1 environment for the 
called subroutine by passing the caller's registers (except 0, 1 and 
15). Return from the subroutine is directly to the PL/1 caller (via 
the 31-Amode interface when needed). 


BINTFAC TITLE ‘BINTFAC - PL/1 SUBROUTINE INTERFACE’ 
BINTFAC2 CSECT 

BINTFAC 

C'BINTFAC’ ,AL1(7) ID FOR PL/1 
BINTFAC OH 


(14,12),,* SAVE CALLER'S REGISTERS 
R2,R15 ESTABLISH BASE REGISTER 
BINTFAC ,R2 
R15,R15 CLEAR 
R15,7,1(R1) LOAD NAME ADDRESS 
O(R15) ,X'CO' POINTING TO ALPHA CHARACTER? 
NAMEADOK YES - BINTFAC DCL OPTIONS(ASM) 
R15,0(,R15) LOAD NAME ADDRESS FROM LOCATOR 
NAMEADOK OH 

RO,R15 PUT NAME ADDR IN RO FOR MODCNTRL 
O(R1) ,X'80’ ONLY ONE PARM PASSED? 

NO 

CLEAR - NO OTHER PARMS 


MOREPARM 
BUMP PARM LIST POINTER 
PARMSOK 


MODCNTRL ACTION=LINK ,MODNAME=(0) SET UP FOR CALL 
*-2 OVERLAY BALR INSTRUCTION 
R14,12(,R13) RELOAD CALLER'S RETURN ADDRESS 
R2,R12,28(R13) RELOAD REST OF CALLER’S REGS 
R15 NOW GO TO DYNLLOAD 


Figure E-1. Sample PL/1 Subroutine Interface 


227 


Page 
ACCESS function (DFA) 110 
ADABAS data base 15,52 
ALLOCATE function (DFA) 110 
ALLOCATE PL/1 statement 45 
Alternate Format Table 206-207 
Alternate Index (VSAM) 71 
Alternate Path processing (VSAM) 71 
AMODE linkedit parameter 46,197 
Application programs. 

See Subsystems. 

AMP parameter (VSAM JCL) 67,74 


Arithmetic variables 
Assembler Language 
16,34,46.3,90,95,104-105,110-110.1 


31,46.3-4,210 


AUTOLOK feature 94 
Automatic storage 41,54,56,57,107 
AUTOMATIC variables 16 
--and File Handler 53-54 
--and MVS/XA 46.2 
Back End--defined 11 
Back End Device Table. See Device 
Table. 
Back End Station Table. See 
Station Table. 
Backout -on-the-Fly 6,34 
BASED parameter (MAP macro) 47,133 


--and symbolic map definitions 111,211 


BASED vs NONBASED parameters 46.3 
Batch execution 1,3,30 
Batch Report Table (REPTAPE) 206-207 
BCGROUP macro 205 
BDAM access method 
--DCB 64 
--DD statement parameters 52 
--and exclusive control 57 
--and File Handler Option Codes 65 
--and File Handler Parameters 54 
--and File Handler return codes 66 
--sample inquiry programs 111,169 
--service routines 51,64 
BDW. See Block Descriptor Word. 
BEGIN-blocks (PL/1) 45 
Binary table search 30,110 
BISAM access method 
--DD statement parameters 52 
--and exclusive control 57 
--and ISAM/VSAM compatibility 74 
~-processing 62 
--return codes 63 
--service routines 51,62 
BINTFAC subroutine interface 227 
BLDL parameter (SUBMODS macro) 46 


INDEX 
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Page 
BLDL parameter (SYCTTBL macro) 46 
BLHOT module 29 
BLINE macro 205 
Block Descriptor Word 61 
Broadcast Group 20,75,101,107 
Broadcast Table (PMIBROAD) 205,207 


BROADCST. See Broadcast Table. 
BSAM access method 51-52,57,60-61 
BTAM 11 
--simulator 111,129-131 
--switched devices 21 
BTAMSCTS. See Front End Queue Table. 
BTAMSIM module 131 
BTERM macro 205 
BISAMP table 205 
BTVERB macro 
--and BTVRBTB 17,18 
--and editing 35 
--and priority 21 
--and sample subsystem 130,132,168 
--and subsystem codes 18 
--table summary 205 
BTVRBTB. See Front End Verb Table. 
Cancelled messages 34,46.1 
Change/Display Utility 
--described 16 
--and formatting required, 
fixed text messages 76-77,167 
--and message switching 42 
--and Output Utility 76-77 
--and sample subsystem 167 
--tables used by 207 
Change Table (CHNGTB) 167,180,205,207 
Checkpointing 6,28 
CHNGTB. See Change Table. 
Closing files 51,52,57 
COBOL subroutines 91,210 
COBPUT module 
--calls to 39,97 
--error recovery 98 
--function 39 
--and message flow using EDIT 
and OUTPUT 24 
--and message queuing 97 
--and message switching 35,42,99-100 
--and Output Utility 76 
--return codes 98 


--and sample inquiry 
subsystem 112-125,169-178 
--and subsystem logic using 


EDIT and OUTPUT 37 


Page 
COBSTORF module 100 
Commands (Intercomm) 16,93-94,101 
Company/Report/Terminal Table 206-207 
Constants, defining 41,46.1 
Gonversational subsystem. See 
Subsystems, conversational. 
Conversational time-out 
__(Front End) and FESEND 102 
CONVERSE 
--automatic time-out 88 ,90-92 
--calling format 90 
--and conversation implementation 
options 81 
--described 88 
‘--and ISA 88,92 
~-and MVS/XA 88 
~-and PL1LNK 90 
-~and PMIPL1 90,211 
“<-return codes 91 
=~subsystem logic using 89-91 
CONVERSION condition (PL/1) 45,46 


COUNT PL/1 execution parameter 38 


CREATEGF utility 64 
CREATSIM utility 129-130 
‘--JCL for 134-135 
Data Base interface 15,52,110 
Data conversion 

--and subroutine calls 46 
Data Set Control Table 17 
Data Set Name Sharing (VSAM) 67,71 


Data strings 15,84, 86 
Dataspeed 40 terminal 
DBINT function 

DBMS support 15,24,34,52,110 
DDQ. See Dynamic Data Queuing. 


Debugging program problems 129 
See also DWSSNAP Facility. 
DEFINED PL/1 statement 41,210 


DESOOO data set 167,205 
Device control characters 
DEVICE macro 

Device Table (PMIDEVTB) 


206 
17,101,206-207 


DFA. See Dynamic File Allocation. 

Dispatcher 12,104,110,129 
DL/I data base 15,52 
Dope Vectors (PL/1-F) 209 


DSA. See Dynamic Storage Area. 

DSCT. See Data Set Control Table. 

DSN option. See Data Set Name Sharing. 
Dumps. 129 
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DWSSNAP Facility 


--coding format 46.2 
--described 46.1 
--examples 46.3 
--parameters 46.2 
Dynamic Data Queuing 
--and conversational subsystem 
81,86-87 
--described 15 
--and Front End Data Queuing 107 
--and Message Mapping Utilities 47 
--and segmented input messages 22,30 
--subroutine entry names 110 
--types of queues 86 
--use of 30,86-87 
Dynamic File Allocation 15,110 
Dynamic file backout 6,34 


Dynamic loaded subsystems 18,39,131,168 


--and CONVERSE 88,92 
--and dynamic linkedit 30,95 
--linkedit of 197 
--and MVS/XA 46-46.1,95 
Dynamic Storage Area (DSA) 
--and CONVERSE 90 
--and DWSSNAP Facility 46.1-46.3 
--and File Handler 54 
--and intersubsystem queuing 97 
--and MVS/XA storage 46-46.1,54 
--and order of data fields 46.2 
--and PMIPL1 210 
--and Reentrant Subsystems 16 
--and SPAC parameter (SYCTTBL) 18 
--and subroutine interface 227 
DYNLLOAD module 46,106,211 
--and mode switching 105 
ECHOPL1 sample subsystem 43-44.2 


ECT. See Edit Control Table. 

EDIT. See Edit Utility. 

EDIT parameter (BTVERB macro) 35,37 
Edit Control Table (PMIVERBS) 


-~-assoclated components 207 
--described 49 
--macros 206 
-~-and message flow using EDIT 

and OUTPUT 24 
--and required fields 50 
--and subsystem testing 167,180 


--and USRVERBS 167,180 
Edit subroutines 


c Edit Utility 


--concepts 14,49 
--and CONVERSE 91 
--function 14 
--message flow using 24-25 
--and message switching 42 
--and MSGHUSR field 21 
--processing results 49-50 
--and sample subsystem 169 
--subsystem logic using 37-38 
--and subsystem testing 167,183 
--tables used by 17,207 
--using 49-50 
--and verb message 
identifier (MSGHVMI) 35,42,183 
ENTRY EXTERNAL 39,210,227 
ENTRY OPTIONS 39,95,110,200, 210 
Entry sequenced data sets 54,67,69 
Error messages 
--and calls to service routines 55 
--and conversational subsystems 79 
--and debugging 129 
--and Edit Utility 50 


ESA. See MVS/XA. 

ESDS. See Entry sequenced data sets. 

ESS. See Extended Security System. 

Exclusive Control 
--and File Handler Control Word 53 
--for non-VSAM files 57-59 
-~-processing (file/record) 57-58 
--releasing (file/record) 59 
--and resource control 110.1 
--and Store/Fetch 85 
--for VSAM files 70 

EXEC JCL statement parameter 131,168 


EXTDSCT. See External DSCT. 
Extended Security System 
15,29,110-110.1 
110.1 
53-54,56-57,59,68 


EXTERM macro 
External DSCT 


FAR. See File Attribute Record. 

FDETL macro 205 
FDHDR macro 205 
FDR. See File Description Records. 
FECM. 106 


See Front End Control Messages. 


FECMDDQ. See Front End Data Queuing. 

FECMFDBK. See Front End Feedback 
Messages. 

FECMRLSE. See Front End Queue Release. 


Feedback codes (VSAM) 70,73 


Page 
FENETWRK table 136,205 
FESEND a 

--described 101-102 
--and conversational time-out 102 
--and CONVERSE time-out message 90 
--and FESENDC entry point 94,101 
--and Front End Control Messages — 106 
--and Front End Feedback Messages -108 
--and Front End Queue Release 102,108 
--function 14,35 
--and INTERLOG log codes 27-29 
--and LOCK/UNLK commands 94 
--and message flow using EDIT 

and OUTPUT 24-25 
--and message flow using MMU 22-23 


--and message header altering 21,40,42 


--and Message Mapping 

Utilities 22-23,47 
--and MSGHRSC and MSGHRSCH 40 
--option codes 102 
--and Output Utility 24-25 ,38,75 
--return codes . 102, 
--and subsystem coding . 35,40. 
--and subsystem logic using . uy 

EDIT and OUTPUT 38 


--and subsystem logic using MMU 36 

--and VTAM 102,108 
FESENDC entry point 94,101-102,106,108 
FETCH function ' 84-85 
FETCH PL/1 statement * 45, 
FHCW. See File Handler Control Word. _ 
FILE PL/1 statement 52. 


FILE command 56,57. 

File access. See File Handler. 

File Attribute oe 
Record 17,51,56,61,62,67,71,207 

File Description Records 76,167,205,207 


--illustrated 182 
File Handler hay 
--access methods supported 52. 
--and Automatic Storage 54 
--and batch execution ~ 30. 
--and closing a file 52,57 
--control areas 53 
--and CONVERSE Ot. 
--described 12,52-52 
--and direct access files 64-66, 
--and DSA 4 
--error checking 755 
--exclusive control en 
--non-VSAM files 57.529 
--VSAM files 59,70 


‘--general concepts 


51-52 
--and indexed sequential files 62-63 
--and ISA 53 
--and ISAM/VSAM compatibility 74 
-rand message flow using EDIT 
"and OUTPUT 24-25 
--and message flow using MMU 22-23 
--and MVS/XA 46,54-57 
--parameters 53-54 
-~-and PENTRY 54 
--and PMIPL1 54 


roreturn codes 53,55-56,59-60,63,66,73 


--and sample inquiry subsystem 111 
---SELECT and RELEASE functions 56 
--and sequential access files 60-61 
---service routines 51,54-55 
--and Static Storage 54 
7 subsystem processing 52-53 


--tables used 205,207 


--and undefined record format 61 
--and variable length records 61 
«-and VSAM 59,67-73 
File Handler Control Word 

and closing a file 57 
_--~described 53-54 
werand direct access files 64-65 
sand exclusive control 57 
~-and indexed sequential files 62 
--and ISAM/VSAM compatibility 74 
--return codes 55 
---and undefined records 61 
--and VSAM files 69-73 
File Handler Data Set Control 

Table 17,205 

File Recovery feature 6,51,103 
File Table 206-207 
FLOW PL/1 execution parameter 38 
Flushed messages 21,29 
Format Description Record. 

See File Description Records. 
FREE PL/1 statement 45 
Front End 

--defined ll 
--and TP queuing interface 12 
Front End Control Messages 106-109 
--and FESEND 101 
ov-return codes 106 
Front End Data Queuing 30,107,108 
Front End Feedback Messages 107-108 
Front End Network Configuration 

Table 17,205,207 
Front End Queue Release 102,108-109 
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Page 
Front End Queue Table (BTAMSCTS) 
205,207 
Front End Verb Table (BIVRBTB) 
-~-and AUTOLOK 94 
--creation of 17,205,207 
--and CONVERSE 90-91 
--and editing 37,49 
--function 17-18 
--and message processing (VMI) 35 
-~-and USRBTVRB 18,130,132,168 
GENFTBLE macro 206 
GET service routine 
--calling format 60,62 
--and exclusive control 57-59 
--function 51 
--and indexed sequential files 62 
--and ISAM/VSAM compatibilty 70,74 
-~-and sequential access files 60-61 


--and subsystem processing 52 


GETDATE macro 110.1 
GETV service routine 
--calling format 67-68,72 
--and exclusive control 70 
--and FHCW reason codes 70 
--function 51 
--and subsystem processing 52 
--and VSAM files 67-68 
--and VSAM processing options 69-71 
HEAP PL/1 execution parameter 38 
HPRTY parameter (BTVERB macro) 21 
IAM access method 52,54 
IBM 2740 Terminal 21 
IBM 3270 Display Station 21,49,131 
--and simulation testing 130 
IBMB.... PL/1 routines 105-106 ,198 
ICOMLINK macro 136,185 
IDMS data base 15,52 
IJKDELAY service routine 30,110.1 
IJKPRINT service routine 30 
Indicative dumps 129 
Initial Storage Area (ISA) 
--and CONVERSE 88 ,92 
--and DWSSNAP Facility 46.1-46.3 
--and File Handler 53,56,57 
--and Reentrant Subsystems 16 
--and REPORT option 38 
--and SPAC parameter 18,41 
--and subsystem coding 41 
--and user subroutines 38,105 
--and variables 41,45 


{ Page 
INTDEQ macro 110.1 
INTENQ macro 110.1 


re 


INTERCOMM environment 9-15 


INTERCOMM tables 17,205-207 
--REENTSBS subroutine table 
39 ,95-97,206 
INTERLOG file 26-29,103,161-166,191-196 
--JCL for 138 
INTFETCH function 110 
INTLOAD module 
--defined 39 
--JCL procedures 197-198 
--and loadable programs 105-106 
--and MVS/XA 46-46.1,95 
--and PLIV 106 ,197 
--and service routine calls 95 
--and testing a subsystem 130 
INTPOST macro 110.1 


INTSCT module 
--and USRSCTS 


18,130,167,206 
18 ,130,132,167,180 


INTSORT Facility 109-110 
--return codes 110 
INTSORTC entry point 109 
INTSPA module 82-83 ,206 
INTSTORE function 110 
INTTIME macro 110.1 
INTUNSTO function 110 
INTWAIT macro 110.1 

ISA. See Initial Storage Area. 

ISAM (see also BISAM and QISAM) 
--access by File Handler 52 
--File Handler processing 62 
--File Handler return codes 63 
--File Handler service routine 

parameters 54 
--and VSAM 67,70,73,74 

ITEM macro 206 

IXFCHKPT module 28 

IXFDSCTA macro 205 

IXFDSCT1/2/3/n 205,207 

IXFLOG (File Recovery logging) 28 

JCL 
--CREATSIM utility 134-135 


--DD statement for File Handler 51-52 
--for direct access files 64-66 
--for indexed sequential files 62 
--for ISAM/VSAM compatibility 74 
--PL/1 procedures 197 
--sample simulation Mode 136-138 
--sample Test Mode 185-187 
--for VSAM files 67,187 


JOBCAT DD statement (VSAM) 131 
Journaling. See Logging. 


Key Table (Change/Display) 206-207 
Key sequenced data sets (VSAM) 34, 67, 71 
KEYCREAT utility " 64 
KSDS. See Key sequenced data sets. 


LANG parameter (SYCTTBL macro) 18',46 
LAYOUT macro 110.1 
LCOMP macro "9905 
LIBELINK procedure 132,180 
LIMCT parameter (JCL) * 52,64 
LINE macro . 206 
Line control : ‘6-7 
LINEGRP macro , 905 
Linkedit 130,136-137,168, 185-186", 197 
--and MVS/XA 45,,95,197 
LKEDT procedure 137,186 
LNAME parameter (SUBMODS Macro) | a 
‘46, 104- 106 
LOAD command ; 30 


LOADNAM parameter (SYCTTBL macro) '18 , 46 
Locator/Descriptors 209-210 
--and PLILNK parameter (SYCTTBL) +*19 


--and pointer variables 3146.3 
LOCK command ‘93-94 
Log Analysis utility 21,26 
Log codes 26-29 ,46.1,103 
Logging. See INTERLOG file, LOGPUT. 
LOGCHARS table 207 
LOGPROC module "28 
LOGPRINT utility 21,26 

--sample JCL for 138- 


--sample printout 


161-166 ,191-196 
LOGPUT module soe 


--calling format . 103 
--function "14 
~-and INTERLOG entries 28-29- 


--and user entries to : oes 


INTERLOG 26-27,108 
LOGTROUT table “103 
LSR (pools) option (VSAM) _&, 72 
LUNIT macro °-205 
Macros (Intercomm) yeee? 

--for features 4170.1 

~-for tables 205- ‘206 
MAPCLR function FO 
MAPEND function 34, 36, 48: ;108, "1Té 
MAPFREE function 10 
MAPIN function Se. 


36,46.3,47,48,110711 E7888 
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waPoyT function 36,48,110 
GAPURGE function 110 
egsage ‘Collection 
“-<¢alling format 99 
--and .COBPUT 39,97 
_--function 14 
--and INTERLOG 28-29 
_nzlog .codes 27 
‘sand message flow using 
EDIT and OUTPUT 24-25 
,7-and message flow using MMU 22-23 
“--and message switching 99-100 
--and MSGHMMN 20 
--and MSGHUSR 21 
“acand PMIPL1 99,210 
“yoreturn codes 34,99-100 
Message flow 
“s-using Edit and Output 24-25 
oyrusing MMU 22-23 
Message header 
s--changing 35 
‘;-and CONVERSE 90 
-- described 19-21 
‘--and Message Collection 100-101 


“wand message flow using EDIT 


.., and OUTPUT 24-25 
;-and message flow using MMU 22-23 
“-and message processing logic 35 
--and message routing 18 
--and output messages 35,77 
‘2-specifications for the Output 
' Utility 77 
--and subsystem structure 31,40-41 
rand Test Mode input 183 
r-and user log entries 103 
Message Mapping Utilities 
--and Assembler Language 
-, subroutines 104-105 
--described 14,47 
~tand Front End Control. 
; Messages 107-108 
--function 14 
-:and INTERLOG log codes 27 
> pmMaps for sample subsystem 133 
yxMessage flow using 22-23 
=iand messages to Front End 101 
=<and MSGHVMI 40 
> -processing 22-23,30,47-48 


--and sample inquiry subsystem 111,130 


--service routines 110 
=-dnd subsystem logic 35-36,48 
--and subsystem testing 129,130,131 
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--and symbolic maps 47,111,130,211 


--tables used by 17,207 
Message processing concepts 35-38 
--using MMU 48 
Message switching 42,99 


MMU. See Message Mapping Utilities. 
MMUC command 130,134,139 


MMUVTBL table 207 
MNCL parameter (SYCTTBL 

macro) 19,131,168 
MODCNTRL macro 104,105 
Model 204 data base 15,52 


Monitor control functions 7 


MRINTER module 28 
MRQMNGR module 28-29 
MSGAC module 29 
MSGCOL. See Message Collection. 

MSGHADDR field 20 
MSGHBLK field 20 
MSGHBMN field 20,26,183 
MSGHCON field 20 


MSGHDAT field 20,26,103 


MSGHFLGS field 20 
MSGHLEN field 
--described 20 
--and Front End Control Messages 106 
--and message switching 99-100 
--and output messages 40 
--and user log entries 103 


MSGHLOG field 20,26,103 


MSGHMMN field 20,26 
MSGHQPR field 20 
--and COBPUT call 97 
--described 22 
--and segmented input 76,97,101 
MSGHRETN field 20,34 


MSGHRSC field 


--and assigning verb to terminal 94 
--and COBPUT 97 
--described 20 
--and Message Collection 99 
--and message routing 18,35 
--and message switching 99 
--and output messages 40,77 
--and subsystem logic using 


EDIT and OUTPUT 37 
--and Test Mode 183 
MSGHRSCH field 
--and assigning verb to terminal 94 
--and COBPUT 97 
--described 20 
--and Message Collection 99 


— 


Sd 


C 


--and message routing 18,35 
--and message switching 99 
--and output messages 40,77 
--and subsystem logic using 
EDIT and OUTPUT 37 
--and Test Mode 183 
MSGHSSC field 20,40,106 
MSGHSSCH field 20,40,106 
MSGHTID field 
--described 20 
--and FESEND/FESENDG 101-102 
--and Front End Data Queuing 107 
--and Front End Queue Release 108 
--and message switching 42 
--and Output Utility 75 
--and Store/Fetch facility 84 
--and subsystem coding 40 
--and Test Mode 183 
MSGHTIM field 20,26,103 
MSGHUSR field 20,21 


MSGHVMI field 
--and Change/Display Utility 76-77,167 


--and COBPUT 97 
--described 20,22 
--and Edit Utility 35,38 ,42 
--and FESEND 21,40,101 
--and Front End Control Messages 106 
--and Front End data queuing 107 
--and input messages 35 
--and message processing 35 
--and message switching 35,42 
--and output messages 40 
--and Output Utility 75-77 
--and subsystem logic using 
EDIT and OUTPUT 37 
--and Test Mode 183 
Multitasking (PL/1) 45 
Multiregion System 
--and batch interface 30 
--and COBPUT calls 98 
--and testing 129 
Multithread processing 
--described 4-5 
--and exclusive control 57 
--and message flow using MMU 22 
--and PREPLI 38 
--and reentrant subsystems 16 
--and subsystem testing 131,168 
MVS/XA 
--and PMIPL1 calls 39,46.1,95,210 
--and CONVERSE 88 
--extended storage loading 
requirements 46-46.1 
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--and FECMDDQ ; 107 
--and File Handler calls | 54-3] 
--and PL/1 programs 38-39,46-46.1 
--and sample programs 111),210 


--and subroutine interfaces 
46.1,105-106,227 
--and subsystem coding  46-46.1 


NAME parameter (SUBMODS macro) ' 104-106 


Network Table 17,205,207 
NONBASED vs BASED parameters ~ 46.3 
Nonreentrant subsystems _ , 16 


» 


OFT. See Output Format Table. *” 


On-line environment (described). 1-3 
On-line testing ‘129 
ON-units (PL/1) SO AS, 
OPEN (FAR) option Jeo BL 
Opening files oo "> 51-52 
OPTIONS (PL/1 PROC statement) "18. 
--and user subroutines — 105 
--MAIN procedure , © 31,105 
- -REENTRANT 7 "18,105 
OTQUEUE user exit (VTAM) _ 21 
Output Format Number — " "97,168 
Output Format Table ee 
--associated components a 207 
--creation of eo" 206 
--described oS 76 
--and message flow using _ Do 
EDIT and OUTPUT s  * 24 
--and subsystem testing 168 ,181-182 
Output Utility 
--and COBPUT " 97 
--and CONVERSE , 90 
--described 16,75. 
--and Front End feedback messages 108 
--function 14 
--and INTERLOG log codes 26-27 
--message flow using “24-25 


--message header specifications for 77 


--and message switching _ , 30,42 
--and MSGHQPR L722 
--and MSGHVMI 35,77 
--processing 24,75-76 
--and sample inquiry subsystem ~' “168 
--subsystem logic using 35,37-38 


--and subsystem testing 168 


--tables used by 17,207 
Pad character table 206-207 
PADD macro  ¢ 206 
PADDTBLE. See Pad character table. 


ad” 
Page 

w¢d-erd 

Page Facility”. - 

PAGETBL macro ~ 

PAGETBL table 

PARM nacro. 180,206 


15,47,110,206,207,211 


PATRN macro 206 
Pattern Table (PTRNTBLE) 206-207 
PENTRY. copy member 203 
+rand File Handler 54 
--and MVS/XA 46.1,54 
+and: service routines 46.1,96,110 
“land, subsystem coding 39-40 
>and user subroutines 104 
“and using PMIPL1 39-40,96,104,209 
PUICALLB FL/1 entry 18,39 
PLIDUMP data set . 
‘<>and REPORT, execution option 38 
PLIENTRY, ‘copy member 200 
yeand ‘sample inquiry subsystem 111 
-~and service routines 39-40,95,110 
rand subsystem coding 39-40 
v-ramd user subroutines 104-105 
FLILQGCH copy member 111 
PLIMAIN PL/1 eritry 39 
‘BIRETV PL/1 function 99 
RLISHRE PL/1 module 197-198 
PLIV interface routine, defined 39 
»¢-and INTLOAD 100,106,197 
~~ -and MVS/XA 100 
BLIXPC JCL procedure 197 
PLIXPCL JCL procedure 197 
BEMSGHD copy member 201 
‘+-and subsystem coding 32,41 
e--and sample inquiry subsystem 111 
PL1IHDR copy member 202 
PLILNK parameter (SYCTTBL macro) 
if an 19 ,31,46.3 
--and CONVERSE 90 
Ad.and MMU. 47 
PMIALTRN macro 206 
PMIALTRP. See Alternate Format Table. 
PMIBROAD. See Broadcast Table. 
PMECANC: See USRCANC. 
PMIDEVTB. See Device Table. 
RBHIELEN macro 206 
PHIEXLD Utility 167,205 
PMIFILET. See File Table. 
PMIPL1 interface routine 
“¢-BASED vs NONBASED parameters 46.3 
6e¢+and COBPUT 39 
.S9:rdefined 39,95 
--and dynamically loaded programs 95 
--and DYNLLOAD 105,211 


Page 
--and File Handler 54 
--and JCL procedures 197 
--and MAPIN call 46.3,211 
--and MSGCOL 99 
--and MVS/XA 38 ,46-46.1,95 
--and PAGE (facility) 211 
--parameter area, described 211 


--and passed parameters 
39,46,1,95,104,210-211 
--and REENTSBS 39,95-96 
--routine pointers (REENTSBS) 96-97 
--sample program using 210, 212-226 
--and service routine calls 
39,95,110,209-211 
--and user subroutines 104-106 


PMIRCEND. See Output Format Table. 
PMIRCNTB. See Output Format Table. 
PMIRPTAB. See Company/Report/ 


Terminal Table. 


PMISNAP macro 110.1 
PMISTATB. See Station Table. 

PMISTOP DD statement 38,131 
PMISTOP macro 206 
PMITEST module 167,168 
PMIVERBS. See Edit Control Table. 
PMIWTO macro 110.1 
PMIWTOR macro 110.1 
Pointer variables 31-32 ,47,104,210 
PREPLI module 38,41 


-~-BASED vs NONBASED parameters 46.3 
--and the Edit Utility 35,38,42,49 
--and message processing concepts 35 
--and MVS/XA 38 ,46-46.1 
--and PLIV 39 
--and PL/1 execution parameters 38 
--and SPAC parameter (SYCTTBL) 18,41 
--and subsystem coding 38,41 
PROC PL/1 statement 18 
Procedure name 41 
PTRNTBLE. See Pattern Table. 
PUT service routine 
--calling format 60,62 
--and exclusive control 59 
--function 51 
--and indexed sequential files 62-63 
--and sequential access files 60-61 
--and subsystem processing 52 


--and ISAM/VSAM compatibility 70,74 
PUTV service routine 


--calling format 68,72 
--and exclusive control 70 
--and FHCW reason codes 70 


4 


i 


C 


--function 51 
--and subsystem processing 52 
--and VSAM files 
--and VSAM processing options 69-70 


QBUILD function 
QCLOSE function 87,110 
QISAM access method 


--and exclusive control 57-59 
--and File Handler service 
routines 51-52 ,62 
--and ISAM/VSAM compatibility 74 
QOPEN function 87,110 
QPR. See MSGHQPR field. 
QREAD function 87,110 


QREADX function 87,110 
QWRITE function 
QWRITEX function 


QSAM access method 51-52,57,60 


Queues 
--and COBPUT 97 
--and Dynamic Data queuing 15, 86-87 
--and FESEND 41,101 
--and Front End 11 
--illustrated 23,25 
--and INTERLOG 26 
--and Message Collection 22,24,99 
--and message switching 42 
--and TP interface 12 
--types of DDQs 86 


RBA. See Relative byte address. 
RBN. ee Relative block number. 

RDW. See Record Descriptor Word. 
READ service routine 


--calling format 60,62,64 
--and direct access files 64-66 
--and exclusive control 57-59 
--function 51 
--and indexed sequential 

files 62-63 
--and ISAM/VSAM compatibility 70,74 
--and sequential access files 60-61 


--and subsystem processing 52 


READONLY (FAR) option 51,71 
Reason codes, VSAM 70,73 
Record Descriptor Word 61,68 


RECURSIVE procedures (PL/1) 45 
Reentrant subsystems 


--coding conventions 16,18 ,41 
--environment 33 
--example 32 ,43-44.2 


Page 

--and File Handler 53-54 
--and LANG parameter (S¥CTYBL BS tpet 
macro) - aT FLes 
~-and MNCL parameter (SY¥CTTBL:- eur ag 
macro) 195 131,168: 
--and MVS/XA loading "46-4654" 
-'-structure “= 31232" 
--and user subroutines 105-106,209%+2137 
--vs. nonreentrant subsystems 16528 

REENTSBS table “ 

--creation of ae 6 206, 209 
--described < 39, 95-97 
--function TO 6S! 39°40 
--listing of ue 96-97 
--and service routines i 95, 110, 207 
--and user subroutines © eacenrt 


46.1, 10411063209 
' 97,130,132), 209: 
olat 54 64-66 


--and USRSUBS 
Relative block number 


--example 2 baal 
Relative byte address “54,67-69 
Relative record data set :'« -:- :54,67 
Relative record number. « << 2 34,67-70. 
Relative track and record . ta ok ENTS 

number ar nace) A 
RELEASE PL/1 statement NA EQ 5E 
RELEASE service routine eat. OTR VILES 

--calling format Tr on 1-56 

--and exclusive control SRS 59 

--function . - oR TES 

--return codes ee a) « 

--and subsystem processing 52-53 

--use of 56-57 

--and VSAM 67,74 
RELEX service routine ‘ 59,74 
REPORT macro 206 
REPORT PL/1 execution parameter 38 
REPTAPE. See Batch Report Table. . 
Resident programs 11,39,92, 105 


RESOURC parameter (SYCTTBL macro) ..° -§9 
RESOURCE macro 19 
Resource Manager ase ¥2 
RESTART parameter (SYCTTBL macro) “46.4 


Restart/recovery 21526, 46¢% 
Restarted messages ~ 46.5F,88 
Retriever (module) ares 4: | 
Return codes ‘ o sl MLA 
--from COBPUT . , iv, 2a (98 
--from CONVERSE - Gras -92 
--from FECM calls ‘ c 106 
--from FESEND/FESENDC 338.4102 
38 Se eh come 


«+from File Handler 


--BDAM “ 66 
/¢-ISAM 63 
*-outline of - §5 
vd > RALEX . 59 

~ -SELECT/RELEASE 56 
"4>sequential:access (SAM) . 60 
- &~VSAM 69-70,73 
@efrom Front End Control 
+, Message facility 106 
from INTSORTG . ue 110 
-ifrom LOGPUT : 103 
--from Message Collection 99,210 
&-from queuing routine 41 
2-from subroutines 104,111 
--from subsystems . 22,31,34 

REUSE parameter (SYCTTBL macro) 46 
RLSE’ command 108 


RMODE lLinkedit. parameter 46,197 
RRDS.” -See@ Relative record data set. 
REN. See Relative record number. 


RINLINK macro 211 
SAM. See System Accounting and 
. Measurement. 
Sample subroutine. 
I CSQRLLB) 2 i 111,126-128.1 
Sample subsystems: 112,169 
--with PMIPL1 calis 43,212 
Save area’, .- 104-105 ,211 
SBA sequence (IBM 3270) 21,49 


SBSP parameter (SYCTTBL macro) 18 
SCT.. See Subsystm Control Table. 


SECTEST macro (ESS) 110.1 
SECUSER routine (ESS) 15 
Segmented messages 

>-<Cand COBPUT 97 
--and DDQ . 30 
--and MSGHQPR . 22,76,97 
‘~-and Output Utility 76-77 
SELECT service routine 

--calling format 56 
‘«-“funetion 51 
\*sand ISAM/VSAM compatibility 74 
Wirdturn codes 56 
{--arld -subsystem processing 52-53 
i#-use of 56 
t-sand VSAM 67 
Service routines (Intercomm) 

--calls to 39-40 ,46,95-96 


SETGLGBE:.gloBal table |. . 46 
Share options (VSAM) 70-71 
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Shared Library (PL/1 V2) 197-198 
SIMCRTA utility 168 
Simulation Mode 
--and BTAM simulator 111,129-131 
--execution JCL 138 
--input messages 134-135 
--linkedit JCL 136-137 
--logging 27 


--output from 139-158 
SIM3270 module 129,131 
--printout from 131,139-158 
Single-thread processing 4,131,168 


Snap 87 46.1 
Snap program areas 46.1,110.1 
Snaps, Test Mode 167,188-190 
SNAPDD data set 46.1 
Sort Facility 109-110 
SPA. See System Parameter Area. 

SPAC parameter (SYCTTBL macro) 18,41,45 


SPAEXT. See System Parameter Area. 
SPALIST macro 17,206 
SPIE PL/1 execution parameter 38 
SSCONV macro 110.1 
SSSTART macro 110.1 
SSTEST macro 110.1 
SSSTOP macro 110.1 
STAE PL/1 execution parameter 38 
STATION macro 206 
Static storage 
--and constants 41 
--and File Handler 54 
Station Table (PMISTATB) 17,101,206-207 
Statistics 6,26 
STEPCAT DD statement (VSAM) 131 
STORAGE compiler option 18 
STORE function 84-85 
Store/Fetch facility 
--and conversational subsystems 
81,84-85 
--and CONVERSE 88 
--function 15 
--and MMU maps 130 
--service routines 110 
--use of 30,84-85 


SUBMODS macro 
46-46.1,104-106,110,130,206,209-210, 227 


Subroutines 38-40, 46,104-106,209-210 
--and CONVERSE 91 
--and dynamic linkedit 30 
--and linkedit of 105,197 
--and MVS/XA 39,46-46.1,105 
--and PL/1 interface program 105,227 
--sample 


~ 


wv 


111,126-128.1 7 


iS Subsystems 


ed 


c 


--coding 31-46.4 
~-coding conventions 45-46 
--conversational 

--and CONVERSE 88-92 
--design considerations 93-94 
--and Dynamic Data Queuing 86-87 
--general concepts 79-80 
--implementation 81 
--and Store/Fetch 84-85 
--and USERSPA 82-83 
--defined 9-10 
--and dynamic linkedit 30 
--and file access functions 51 
~-and File Handler 52-55 
--illustration of 32 ,43-44.2 
--Intercomm-supplied 16 


--and linkedit of 105,197 


--and message processing 35-38 
--and message switching 42,99 
--and MVS/XA 38-39,46-46.1 
--nonreentrant 16,18 
--and output messages 107-109 


--parameters passed to 
31-33,40-41,46.3-4 


--reentrant 16,18,31-33,105 
--return codes from 34 
--sample inquiry 111,167,210 
--structure 31-32,34 
--testing 111,129-196 
--time controlled processing 30 
See also Reentrant subsystems. 
Subsystem Control Table (SCT) 
--creation of 18,206 
--function 17-18 
--and message flow using EDIT 
and OUTPUT 24 
--and message flow using MMU 22 
--and RESOURCE macro 19 
--and subsystem entry point 41 
--and subsystem structure 31-32 
--and subsystem testing 130,167 


Subsystem Controller 


--and COBPUT return codes 97-98 
--function 12 
--and File Handler return codes 55 
--and inter-subsystem queuing 97 
--and INTERLOG 28-29 
--and message processing concepts 35 
--and PREPLI 38 
--and return codes 34,41,97,99-100 
--and subsystem structure 31-34 
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SUBTASK macro 
--and Multitasking <= Foal T pes 5 


Switched devices 
--and MSGHUSR Blak 
~-and Edit Utility ; ale 


SWMODE module 46',106 

SYCTTBL macro ee 
--and Front End Queue Table See 2205 
--function z +47 
--and INTSCT 18,130, 132%, 267 180 
--and MVS/XA loading reek 46 
--and nonreentrant subsystems - 18 
--parameters 23 1819 
--and RESOURCE macro ool moti dg 
--and restarted messages - <i ‘hOD 


--and sample inquiry subsystem 5: 111 
--and Subsystem Control Table <: * 

aT 17-18, ZO: 

SYCT400 module is 29:45. 

See also Subsystem Controller: :.. ~ Ted 


SYMPL1 data set .£'130,197,199: 
SYMREL data set is B2197, ISP. 
SYMUSR data set Do far B62 82: 
SYSPRINT (SYSOUT data set) 30,38 
System Accounting and "liye 627 HAS 
Measurement (SAM) Doane tt 21021 
System components and programs..; 22: 22° 
11-%5.,30,,110 

System control commands: 30;93-94, LOL 


System log. See INTERLOG 'ffle# 33. - 
System Parameter Area/List (SPA) .§ 7x2 
--and associated components 207 
--and conversational subsystems - ‘81-83 
--creation of uw 206. 
--function ° I? 
--and subsystem structure 31-33 
--and system separator character.:: Boga 
--and USERSPA declaration © : 63 
System Parameter Table. See So 
System Parameter Area. =. 4%." i s-- 
System 2K data base Sr, 52 
Systems Operation Control . + OT Gae 
on saan 
Table sort (INTSORT) “7 £2109-110 
Tables (Intercomm) ED, 205-207 
TCAM © © *£42,;130 


TCTV parameter (SYCTTBL macro) 19 S210. 1 

Teletype Terminal . 21 
Terminal control Sf 346-7 

Test Mode : 26; 121, 129; E67 
Test input messages -- 

111,130, 134- 135, 168s -183- 184 

t 3 VIG: 


reset 
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TEST PL/1 execution parameter 38 
Testing Subsystems 111,129,167 
Thread 
--defined 4,16 
--dumps of (debugging) 129 
--and File Handler control areas 53 
--and MNCL 19 
--and RELEASE 56 
Thread number 21 
Time-controlled processing 30 


Time-out 19,88,91 


TOTAL data base 15,52 
TP interface 12 
Transaction codes/identifiers 17-18 
Transactions 

--described 1-3 

--sample inquiry 111 
TTR. See Relative Track and 

Record Number. 
TYPE parameter (SUBMODS macro) 46,210 
Undefined records 61 
UNLK command 93-94 
UNSTORE function 85 
USAGE parameter (SUBMODS macro) 46 
User exits. 30,34 
User logging 26-27 
See also LOGPUT. 
USERS PA 81-84,88 
USRBTLOG module (user exit) 29 
USRBTVRB 18,130,132,168 
USRCANC module (user exit) 34,55 
USRSCTS 18 ,130,132,167,180 
USRSUBS 97,110,130,132,227 

--and user subroutines 104-106 , 209 
USRTRACK macro 110.1 
USRVERBS 167,180 
Variable data 16 
Variable-length record 61 
VCT macro 205 
VERB macro 180,206 
Verb Table. See Front End Verb Table. 
VERBGEN macro 206 
VERBTBL. See Edit Control Table. 


VMI (Verb Message Identifier). 
MSGHVMI field. 
VSAM access method 


See 


--DD statement parameters 67 
--and Dynamic File Allocation 15 
--FAR options for 67 


--File Handler processing 


240 


--alternate index, keyed files 71 
--alternate path processing 71 
--call summary 72-73 
--example of use 111 
--exclusive control 59,70 
--File Handler Control Word 

reason codes 55,70-73 
--file types supported 67 
--GETV and PUTV 67-68 
--processing options 69-70 


--File Handler Service 
routines §1-52,54,67-68 
--ISAM/VSAM compatibility 67,70,73,74 


--POINT processing 69 
--sample inquiry subsystem 111 
- -SHAREOPTIONs 70-71 
VTAM 11,102,108,130 
VTISAMP table 205 
WRITE service routine 
--calling format 60,62,64 
--and direct access files 64-65 
--and exclusive control 57-59 
-~-function 51 
--and indexed sequential files 62-63 
--and ISAM/VSAM compatibility 70,74 
--and sequential access files 60-61 


--and subsystem processing 52 


WRITEOVER (FAR) option 56 
--and VSAM ESDS files 67 

XA. See MVS/XA. 

ZERODIVIDE condition (PL/1) 45,46 


